API仕様書書くならswagger v2.0からv3.0に変更する際のポイント

はじめに

最近、API仕様書の作成にswaggerを使い始めてswagger2.0と、openapi3.0.0で作成しました。その時にバージョンの違いで記載方法に変更点があったので、メモ代わりとして記載します。

v2.0

とりあえず一番シンプルな形

swagger: '2.0'
paths:
  /api/regist:
    post:
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: hoge_id
          in: query
          description: クエリパラメータ
          type: integer
          required: true
        - name: hoge_name
          in: formData
          description: 名前
          required: true
          type: string
        - name: age
          in: formData
          description: 年齢
          required: true
          type: string
        - name: comment
          in: formData
          description: コメント
          type: string
          required: true
          maxLength: 1000
    responses:
      200:
        description: ok

v3.0

openapi: 3.0.0
paths:
  /api/regist:
    post:
      parameters:
        - in: query
          name: id
          required: true
          description: クエリパラメータ
          schema:
            $ref: '#/components/schemas/id'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RequestBody'
      responses:
        200:
          description: ok
components:
  schemas:
    id:
      type: string
      example: '1'
    name:
      description: 名前
      required:
        - name
      type: string
      example: テスト太郎
    age:
      description: 年齢
      required:
        - age
      type: string
      example: '18'
    comment:
      description: コメント
      required:
        - comment
      type: string
      maxLength: 1000
      example: コメントコメント
    RequestBody:
      type: object
      required:
        - name
        - age
        - comment
      properties:
        name:
          $ref: '#/components/schemas/name'
        age:
          $ref: '#/components/schemas/age'
        comment:
          $ref: '#/components/schemas/comment'

v3.0との変更点

• bodyとformDataがrequestBodyにまとめられる
• schemaの定義方法

v2.0
definitions:
  - comment:
v3.0
components:
  schemas:
    - comment:

• typeはschemaで定義
• required: trueではなく対象を指定
• 見た目：v3.0ではdescriptionの内容がmodelsの中に記載

さいごに

個人的にv2.0の方がdescriptionが見やすいので、v3.0は好ましくないですね..。
お客さんに見せる事を考えるとdescriptionが見やすい位置にあることも重要ですし。