メインコンテンツまでスキップ

OpenAPI

参考URL
参考URL(これが一番参考になる)
openapiをチームに共有する
OpenAPIを分割する

コード自動生成やモックサーバーに活用させることで徹底したスキーマファーストな開発を行うことができる。

覚えるべき大項目​

openapi: 3.0.3  # [必須] Open API バージョンを指定します
info:           # [必須] API 定義の基本情報を記載します
  ...
servers:        # API サーバの情報を記載します
  ...
paths:          # [必須] エンドポイントのリクエストやレスポンスを記載する。メインとなる部分
  ...
components:     # 共通部分をここにまとめておきます
  ...

各フィールド​

わかりやすい
参考URL

infoフィールド​

必須となるフィールドはtitleとversion。

summary vs description​

summary is short, description is more detailed. Think of the summary as a short one or two sentence explanation of what the intended purpose of the element is. You won't be able to describe all the subtle details, but at a high level, it should be able to explain the purpose of the element.

summaryは短く、descriptionはより詳細に。
要約は、その要素の意図する目的が何であるかを1～2文の短い文章で説明したものだと考える。
微妙なディテールをすべて記述することはできないでしょうが、高いレベルで、その要素の目的を説明できるはず。

serverフィールド​

サーバの情報を定義するフィールド
※server は必須でないのでなくてもいい。

ただし記載するとAPIエンドポイントに対するベースURLとして機能する（3.0から） リファレンス

また以下もオススメ

ここで variables を使って任意のホスト、ポートを設定できるようにすることで、この API を各個人の開発環境などからテストすることができます。

tags​

APIで使用されるタグの情報を定義するフィールドのリスト。
各種ツールによってパースされる際は、記述された順序で出力される。
タグ名はユニークで無ければならない。
エンドポイントをグルーピングし、意味のある塊として扱うために定義する。
各エンドポイントでtagsに指定することで定義をタグで分類できる。

エンドポイント​

参考URL

エンドポイントの情報を定義するフィールド。これがメイン
エンドポイントは操作対象の名詞にすること。
名詞は人、もの、場所など、物事の名称をあらわす自立語。体言ともいい、活用がなく単独で主語になる。
「犬」「東京」「私」などが名詞。

paths​

各種APIのエンドポイントを指定する。
serversで定義したURLにこのパスを結合したものが最終的なエンドポイントとなる。

書式としては以下

paths:
  /health:
    get:
      summary: Nid API ヘルスチェック
      tags: [api, v1, health] # グルーピングする
      description: 後続のDBに対し select 1; を投げて成功すれば 204 No Content を返す。失敗すれば Internal Server Error を返す。
      operationId: get-health_check # operationIdってなにさというと、OpenAPIのOperation Objectの一項目で、操作を識別するための一意な文字列のこと
      responses:
        '204':
          description: APIサーバが生きている場合

付与するとパーマリンクが発行できるみたい（ReDocだと）
OpenAPIを利用するツールで operationId を利用できるため付与する。

components​

参考URL

componentsはpaths等から使えるコンポーネントを書く（別フィールドから $ref で参照する。）
componentsを使うと記述量が減る、APIのSchemaとして登録されるのでAPI利用者によりわかりやすく表記される。

  • schemas UserやProduct等のモデル

  • requestBodies リクエストボディ

  • responses APIレスポンス

  • headers リクエストヘッダー

  • parameters 更なる拡張 各リクエストパラメーターを配列で定義します。inはパラメーターをセットする場所。 query : クエリストリング formData : フォーム header : HTTPヘッダー path : パス body : ボディー

API定義で再利用可能なオブジェクトを定義できる。

allOf​

allOfはスキーマを合わせるときに使用する。
下記の例はMessagesのcomponentとWebhooksのcomponentを合わせるという意味になる。

allOf:
    - $ref: '#/components/schemas/Messages'
    - $ref: '#/components/schemas/Webhooks'

oneOf​

１つのステータスコードに対して複数のレスポンスを定義 (oneOf)

oneOfはどちらかが適用されるという意味で、選択肢を表したい時に便利。

oneOf:
    - $ref: '#/components/schemas/Messages'
    - $ref: '#/components/schemas/Webhooks'

Tips​

OpenAPI（Swagger）のAPI開発Docker環境を整備した（yaml分割編集、SwaggerUI表示、モックサーバー、静的HTML出力）

に最終更新