API設計 OpenAPI (Swagger) テンプレート

利用ツール

・VSCode

VSCodeプラグイン

・Swagger Viewer
shift + option + p (mac) でビューワーを表示
※ビューワーを見ながら作成するのがおすすめ

テンプレート

拡張子は「yml」
ファイル名は任意

# vscode shift + option + p
openapi: "3.0.0"

info: #APIのメタデータ
  title: "APIの名称(必須)"
  description: |
    #APIの簡潔な説明
    - Get 説明
    - Post 説明
  termsOfService: "https://tastylog.com/terms/" #APIの利用規約のURL
  contact: #コンタクト情報。(サポートページのURLやメールアドレス等)
    name: "Customer Support"
    url: "https://test.com/support/"
    email: "[e-mail]"
  license: #ライセンス情報
    name: "MIT License"
    url: "https://opensource.org/licenses/MIT"
  version: "1.0.0" #APIドキュメントのバージョン(必須)

servers: #APIを提供するサーバ
- url: "http://localhost:{port}" #APIサーバーのURL
  description: "APIサーバーの説明1"
  variables:
    port:
      description: "値の説明"
      enum: ["3000", "8080"] #利用できる値
      default: "3000"
- url: "http://localhost/{version}" #APIサーバーのURL
  description: "APIサーバーの説明2"
  variables:
    version:
      description: "値の説明"
      enum: ["1.0", "2.0"] #利用できるバージョン
      default: "1.0"
- url: "https://api.test.com/v1"
  description: "API Test"

tags: #APIで使用されるタグのリスト。各種ツールによってパースされる際は、記述された順序で出力される。タグ名はユニークで無ければならない。
- name: "reviews" #タグの名前
  description: "タグの説明" 

paths: #APIで利用可能なエンドポイントやメソッド
  "/shops/{shopId}/reviews": #各エンドポイントのパス。serversで定義したURLにこのパスを結合したものが最終的なエンドポイントとなる
    get:
      summary: "エンドポイントの説明"
      description: "エンドポイントの簡潔な説明"
      tags: ["reviews"]
      parameters:
      - name: shopId #リクエストパラメータ
        description: "パラメータの説明"
        in: path #パラメータの場所 query header path cookieのどれか。
        required: true #必須パラメータならtrue
        schema: { type: string } #パラメータの型
        example: "渡せるパラメータの例"
      responses:
        "200": #ステータスコード
          description: "Success operation レスポンスの説明"
          content: #レスポンスボディ
            application/json: #メディアタイプ
              schema: #データの定義
                type: array
                items:
                  $ref: "#/components/schemas/Review"
      security: []
    post:
      summary: "Create new review"
      description: "Create specified shop's new review"
      tags: ["reviews"]
      parameters:
      - name: shopId
        in: path
        description: "Shop identifier"
        required: true
        schema: { type: string }
      requestBody: #リクエストボディ
        description: "リクエストボディの説明"
        required: true #リクエストボディが必須なるtrue
        content: #リクエストボディの中身
          application/json: #メディアタイプ
            schema:
              # type: string #データの型 書き方1
              # type: object #データの型 書き方2
              # properties: #objectの場合
              #   score: { type: integer }
              #   comment: { type: string }
              $ref: "#/components/schemas/Review" #変数の利用 書き方3
      responses:
        "201": #成功
          description: "Success operation"
          headers:
            location: #位置
              description: "ロケーションのデータの説明"
              schema: { type: string, format: url }
        "400": #エラー
          $ref: "#/components/responses/400-BadRequest"
security: #API全体を通して使用可能なセキュリティ仕様
- apikey_auth: []
components: #APIで使用するオブジェクトスキーマ
  schemas:
    Review: #コンポーネントの位置を表す
      type: object
      properties:
        score: { type: integer }
        comment: { type: string }
    Error:
      type: object
      properties:
        code: { type: string } #エラーコード
        type: { type: string } #エラーの型
        message: { type: string } #エラーメッセージの型
        errors: #エラーの詳細
          type: array
          items:
            type: object
            properties:
              field: { type: string }
              code: { type: string }
  responses:
    400-BadRequest:
      description: "Client side error"
      content:
        application/json: #メディアタイプ
          schema:
            $ref: "#/components/schemas/Error"
  securitySchemes:
    apikey_auth:
      description: "API Key authorization"
      type: apiKey
      name: "X-Api-Key"
      in: header