【API】SwaggerでAPI設計書を作成する方法

Swaggerとは

• RESTful APIを定義するためのフレームワーク

記述形式

下記の2種類

• JSON
• YAML

記述サンプル（YAML）

sample.yml

openapi: "3.0.3"
# 情報：APIに関するメタデータ
info:
  # APIのタイトル（必須）
  title: サンプルAPI
  # APIの説明
  description: |
    サンプルサービスで利用するRestAPIの定義
  # APIの利用規約へのURL
  termsOfService: https://???
  # 連絡先
  contact:
    name: 連絡担当者/組織の識別名
    # 連絡先情報を示すURL
    url: http://url
    # 担当者/組織のメールアドレス
    email: [e-mail]
  # ライセンス
  license:
    name: ライセンス名
    url: ライセンスのURL
  # バージョン（必須）
  version: "1.0"
# サーバー
servers:
  # ターゲットホストへのURL
  - url: http://localhost:4010
    description: 必要に応じて増やしていく
# 使用可能なパスと操作（必須）
paths:
  # パスごとに領域を作成
  /api/account:
    post:
      summary: アカウント登録
      description: |
        新規アカウントの登録
        ## 処理詳細
        - 入力値チェック
        - メールアドレスの登録済み判定
        - アカウント登録

        ## エラーステータス
        - 400: リクエスト不正
          - 入力値不正
          - メールアドレス登録済み
        - 401: 未認証でのコール
        - 500: 内部エラー
      parameters:
        - $ref: "#/components/parameters/authorization"
      requestBody:
        description: |
          以下の項目は設定不要。
          - id
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Account"
      responses:
        201:
          description: |
            正常終了
            - 作成したアカウントの情報
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
        400:
          $ref: "#/components/responses/400_badRequest"
        401:
          $ref: "#/components/responses/401_unauthorized"
        500:
          $ref: "#/components/responses/500_internalError"

components:
  parameters:
    authorization:
      in: header
      name: authorization
      description: APIGateway認証情報
      required: true
      schema:
        type: string

  responses:
    400_badRequest:
      description: パラメータ不備などによるリクエスト不正
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/400_badRequest"
    401_unauthorized:
      description: 認証エラー
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/401_unauthorized"
    500_internalError:
      description: 内部エラー発生
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/500_internalError"

  schemas:
    Account:
      description: |
        アカウント
      allOf:
        - type: object
          properties:
            id:
              description: アカウントID
              type: integer
              format: int32
              example: 20
            name:
              description: 氏名
              type: string
              maxLength: 255
              example: 山田　花子
            gender:
              $ref: "#/components/schemas/EnumGender"
            birthDate:
              description: 生年月日
              type: string
              format: date
              example: "2000-01-01T00:00:00Z"
            email:
              description: メールアドレス
              type: string
              format: email
              maxLength: 255
              example: [e-mail]

    # Enum
    EnumGender:
      description: |
        性別
          * 1 - 男
          * 2 - 女
      type: integer
      enum: [1, 2]

    # HTTPステータス
    400_badRequest:
      type: object
      properties:
        code:
          description: エラーメッセージコード
          type: string
          example: bad_request
    401_unauthorized:
      type: object
      properties:
        code:
          description: エラーメッセージコード
          type: string
          example: unauthorized
    500_internalError:
      type: object
      properties:
        code:
          description: エラーメッセージコード
          type: string
          example: internal_server_error