はじめてのOpenAPI

はじめに

なるべく簡潔にOpenAPIの各所の意味を備忘録として残す。
「Swaggerって何？」とか細かいことはここでは割愛するから許してね。

記述例

以下のように書いてSwagger Editorで見てみると分かりやすいです。

openapi: 3.0.0
info: # APIのメタデータ
  title: Sample API # APIドキュメントのタイトル
  description: 'サンプル' # ドキュメントの説明
  termsOfService: # APIを提供するサーバー
    - url: 'http://localhost:3000'
      description: "ローカル環境"
    - url: 'https://stg-api.sample.com'
      description: "ステージング環境"
  contact: # サポートページのURLやメールアドレス等
    name: API support
    url: http://sample_suppurt.com
    email: [e-mail]
  license: # ライセンス情報
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
paths:
  /api/sample: # エンドポイント
    get: # HTTPリクエスト
      summary: 'サンプルサマリー' # サマリ
      description: '説明' # 説明
      tags:
        - Sample # エンドポイントのタグ
      parameters: # リクエストパラメータ
        - name: name # カラム名
          in: path # パラメータをパス内に含める
          description: '名前' # カラムの説明
          required: true # 必須かどうか
          schema:
            type: integer # 型を指定
      responses: # レスポンス定義
        '200': # HTTP status
          description: 'レスポンスの説明'
          content:
            application/json: # レスポンスの形式指定
              schema: 
                required:
                  - name
                  - email
              type: object
              properties:
                name:
                  description: 名前
                  type: string
                  example: 'サンプル太郎'
components:
  schemas: # スキーマオブジェクトの定義
    User: # モデル名
      type: object # 型
      required: # 必須フィールド
        - id
        - name
      properties:
        id: # プロパティ名
          type: integer # 型 
          format: int64 # フォーマット(int32, int64等)
          example: 1
        name:
          type: string
          example: 'サンプル太郎'

参考

Swagger Documentation
OpenAPI (Swagger) 超入門