API 사양서 작성한다면 swagger v2.0에서 v3.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과의 변경점

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

사이고에게