Web API の Swagger definition を書いてみた

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

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

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

http://swagger.io/swagger.io

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

慣れるまでは Swagger Editor で書くのがいい。入力補完が効くので結構快適。 自分はインストールが面倒なのでライブデモを使った。

editor.swagger.io

Swagger Editor を使うと、Spec を編集するとリアルタイムでドキュメントのプレビューが更新される。 実際にプレビューに表示されるドキュメントはこんな感じ。

f:id:griefworker:20160309111411p:plain