前回の記事に続いてOpenAPIについて書いていきます。
OpenAPIの書き方
Swagger Specによると以下の項目がベースとなっています。
| フィールド名 |
必須 |
説明 |
| openapi |
◯ |
使用するOpenAPI Specificationのバージョン。どのバージョンのフォーマットを使って書くかを指定します。 |
| info |
◯ |
APIのメタデータ。以下Info Object参照 |
| servers |
|
APIサーバーの情報。以下Server Object参照 |
| paths |
◯ |
エンドポイントやメソッド等の情報。以下Paths Object参照 |
| components |
|
レスポンスのスキーマ等、再利用可能なコンポーネントを定義することができます。 |
| security |
|
認証方法等を記述します。 |
| tags |
|
APIで使用されるタグのリスト。複数のエンドポイントをタグでグループ化することができます。 |
| externalDocs |
|
外部ドキュメント |
以下、各項目についてまとめてみました。
| フィールド名 |
必須 |
説明 |
| title |
◯ |
APIのタイトル |
| description |
|
APIの概要 |
| termsOfService |
|
APIの利用規約ページのURL |
| contact |
|
コンタクト情報。以下Contact Object参照 |
| license |
|
ライセンス情報。以下License Object参照 |
| version |
◯ |
APIのバージョン |
| フィールド名 |
必須 |
説明 |
| name |
|
APIを提供する個人や組織の名前 |
| url |
|
コンタクト情報を示すURL |
| email |
|
連絡先メールアドレス |
| フィールド名 |
必須 |
説明 |
| name |
|
ライセンス名 |
| url |
|
ライセンス情報のURL |
| フィールド名 |
必須 |
説明 |
| url |
|
APIサーバーのURL |
| description |
|
APIサーバーの概要 |
| フィールド名 |
必須 |
説明 |
| /{エンドポイントのパス} |
|
以下Path Item Object参照 |
| フィールド名 |
必須 |
説明 |
| summary |
|
エンドポイントのサマリ |
| description |
|
エンドポイントの概要 |
| {HTTPメソッド} |
|
各HTTPメソッド。以下Operation Object参照 |
| フィールド名 |
必須 |
説明 |
| tags |
|
このオペレーションに付けるタグ |
| summary |
|
このオペレーションのサマリ |
| description |
|
このオペレーションの概要 |
| externalDocs |
|
外部ドキュメント |
| operationId |
|
このオペレーションのID |
| parameters |
|
パラメータ。以下Parameter Object参照 |
| requestBody |
|
リクエストボディ。以下Request Body Object参照 |
| responses |
|
レスポンス。以下Responses Object参照 |
| フィールド名 |
必須 |
説明 |
| name |
◯ |
パラメータ名 |
| in |
◯ |
パラメータの種類をquery / path / header / cookieから指定 |
| description |
|
パラメータの説明 |
| required |
|
必須かどうか。inでpathを指定した場合はtrue |
| schema |
|
パラメータの型等を指定 |
| example |
|
パラメータの例 |
| フィールド名 |
必須 |
説明 |
| description |
|
リクエストボディの説明 |
| content |
◯ |
リクエストボディの内容を記述 |
| required |
|
必須かどうか |
| フィールド名 |
必須 |
説明 |
| description |
|
レスポンスの概要 |
| headers |
|
レスポンスヘッダー |
| content |
|
レスポンスボディ |
まとめ
すべての項目を網羅したわけではありませんが、以上の項目を組み合わせればとりあえずOpenAPIは書けるのではないかと思います。
最低限必要な項目がわかれば、たとえば新しく入ったチームやプロダクトであってもざっくりした仕様は掴みやすくなると思います。
より細かい内容についてはぜひドキュメントを読んでみてください。
