Help us understand the problem. What is going on with this article?

Swagger定義ファイルの書き方(超手抜き編)

More than 1 year has passed since last update.

Swagger定義ファイルは、いろいろ定義してバリデーションを厳密にできる反面、ちょっと使おうと思うと、ルールが厳しくて億劫になりがちです。

そこで、必要最低限のSwagger定義ファイルの書き方を備忘録として残しておきます。
いざ本番となるときには、SwaggerのSpecificationに従って厳密に定義してください。

(参考情報)
https://swagger.io/docs/specification/2-0/basic-structure/

一番簡単な定義

結論だけ示すと、一番簡単な定義は以下の通りです。
/pathsのところを参考にしてください。

swagger.yaml
swagger: '2.0'
info:
  version: 'first version'
  title: Sample Api
host: localhost:10010
basePath: /

schemes:
  - http

consumes:
  - application/json
produces:
  - application/json

securityDefinitions:
  basicAuth:
    type: basic
  tokenAuth:
    type: apiKey
    name: Authorization
    in: header

paths:
  /swagger:
    x-swagger-pipe: swagger_raw

  /test_post:
    post:
      x-swagger-router-controller: echo
      operationId: test_post
      parameters:
        - in: body
          name: body
          schema:
            type: object
      responses:
        200:
          description: Success
          schema:
            type: object

  /test_get:
    get:
      x-swagger-router-controller: echo
      operationId: test_get
      parameters:
        - in: query
          name: param
          type: string
      responses:
        200:
          description: Success
          schema:
            type: object

definitions:
  Empty:
    type: "object"
    title: "Empty Schema"

swagger-nodeで最短で立ち上げる

RESTful実行環境に最適なswagger-nodeを使って立ち上げます。
swagger-nodeについては、以下の記事を参考にしてください。

SwaggerでRESTful環境を構築する

> swagger project create first_restful
※Frameworkにはexpressを選択します。

> cd first_restful

Swagger定義ファイルをさきほどのswagger.yamlに置き換えてください。

置き換え対象ファイル:./api/swagger/swagger.yaml

以下のファイルを作成します。

作成ファイル:./api/controllers/echo.js

echo.js
'use strict';

module.exports = {
  test_post: test,
  test_get: test
};

function test(req, res) {
  console.log("calling: test");

  var event = {
    headers: req.headers,
    body: JSON.stringify(req.body),
    path: req.swagger.apiPath,
    httpMethod: req.method,
    queryStringParameters: req.query
  };

  res.json( { event: event } );
}

./api/controllers/hello_world.js はいらないので削除してもよいです。

Restful環境を立ち上げます。

> swagger project start

curlでたたく

さっそく、Web APIを呼び出したく、例えば、curlを使います。

> curl https://localhost:10010/test_get

{“event”:{XXXXXXわらわらXX}}

マイ最速

とはいいつつも、なんだかんだ言って、私は以下が最速

> git clone https://github.com/poruruba/swagger_template.git
> cd swagger_template
> npm install
> node app.js

(参考)
SwaggerでLambdaのデバッグ環境を作る(1)

以上。最短の記事でした。

poruruba
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away