Web API の Swagger definition を書いてみた

Single Page Application(SPA) の開発を効率化できないか検討している。具体的にはクライアント側と Web API 側を平行に開発したい。

Web API のインタフェースを定義しておいて、 Web API が形になるまではスタブを使ってクライアント側を開発すれば、平行に開発できそうだ。これは誰でも思いつくやり方。

そこで白羽の矢が立ったのが Swagger。

Swagger を使ってみた記事はネットでたくさん見つかったけど、その多くが既存の Web API から Swagger を使ってドキュメントを生成するものだった。やりたいのは Web API の Swagger definition を書いて、 Swagger を使ってドキュメントとソースコードの生成。

試しに、ユーザーの CRUD を行う Web API の Swagger definition を書いてみた。

swagger: '2.0'
info:
  title: Sample API
  version: "1.0.0"
basePath: /api/v1
produces:
  - application/json
paths:
  /users:
    get:
      summary: ユーザー一覧取得
      description: ユーザー一覧を取得します。
      parameters:
        - name: page
          description: ページ番号
          in: query
          required: false
          type: integer
      responses:
        200:
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
    post:
      summary: ユーザー登録
      description: ユーザーを 1 件登録します。
      parameters:
        - name: name
          description: ユーザー名
          in: formData
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/User'
  /users/{userId}:
    get:
      summary: ユーザー取得
      description: ユーザーを 1 件取得します。
      parameters:
        - name: userId
          description: ユーザー ID
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/User'
    put:
      summary: ユーザー更新
      description: ユーザーを 1 件更新します。
      parameters:
        - name: userId
          description: ユーザー ID
          in: path
          required: true
          type: string
        - name: name
          description: ユーザー名
          in: formData
          required: false
          type: string
      responses:
        200:
          description: OK
    delete:
      summary: ユーザー削除
      description: ユーザーを 1 件削除します。
      parameters:
        - name: userId
          description: ユーザー ID
          in: path
          required: true
          type: string
      responses:
        200:
          description: OK
definitions:
  User:
    type: object
    properties:
      id:
        type: string
      name:
        type: string