From 37b8df19185c9451527daa7a927ac9e4cce62152 Mon Sep 17 00:00:00 2001 From: Hiroki Takeda Date: Fri, 19 Jan 2024 14:19:21 +0900 Subject: [PATCH 1/2] Format openapi, info, servers and paths sections --- .../OpenAPI_Specification_3.0.3.md | 160 +++++++++++------- 1 file changed, 97 insertions(+), 63 deletions(-) diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index b5f6962a..eb06e57a 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -15,20 +15,20 @@ meta: # はじめに -[OpenAPI Specification 3.0.3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md)に則った API ドキュメントを記述する際のコーディング規約をまとめます。古いバージョンとして[OpenAPI Specification 2.0 の規約](OpenAPI_Specification_2.0.md)がありますので、v2 をご利用の方はこちらをご参照ください。 +本ドキュメントは [OpenAPI Specification 3.0.3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md)に則った API ドキュメントを記述する際のコーディング規約をまとめている。 +旧バージョンである[OpenAPI Specification 2.0 の規約](OpenAPI_Specification_2.0.md)も存在するため、v2を使用している場合はそちらを参照されたい。 -本規約の[前提条件](prerequisite.md)に従い作成されています。ToC向けのLSUDs（Large Set of Unknown Developers）なWeb APIにはマッチしない可能性があります。 - -Web API自体の設計については範囲外としますが、[API 設計標準](API_Design.md)に利用するステータスコードなどは記載しています。 +本規約は[前提条件](prerequisite.md)に基づいて作成されており、ToC向けの LSUDs（Large Set of Unknown Developers）向けの Web API には適合しない場合もあるのでご留意いただきたい。 +Web APIの設計自体はこの規約の範囲外であるが、[API 設計標準](API_Design.md) にステータスコード等の標準を記載しているため、必要に応じて参考にされたい。 ## ファイルフォーマット -[ファイルフォーマット規約](file_standards.md)に準じる。 +[ファイルフォーマット規約](file_standards.md)に従う。 ## OpenAPI ドキュメントの構成要素 -OpenAPI ドキュメントを構成する要素はオブジェクトと呼ばれ、ルートオブジェクトは下記の要素で構成される。 -各種規約を読み進めるにあたってあらかじめ大まかに理解しておくことを推奨する。 +OpenAPI ドキュメントを構成する要素はオブジェクトと呼ばれ、ルートオブジェクトは以下の要素で構成される。 +各種規約を理解する上で、これらの要素を大まかに把握しておくことが重要である。 各オブジェクトの詳細については[公式ドキュメント](https://spec.openapis.org/oas/v3.0.3#openapi-object)を参照されたい。 | フィールド名 | 必須 | 説明 | @@ -49,7 +49,7 @@ OpenAPI ドキュメントを構成する要素はオブジェクトと呼ばれ ## openapi OpenAPI ドキュメントが使用する OpenAPI 仕様のセマンティックバージョン番号を記載する。 -本規約は`3.0.3`を対象としているため、`3.0.3`とする。 +本規約はバージョン`3.0.3`を対象としているため、`3.0.3`とする。 良い例： @@ -77,33 +77,53 @@ openapi: 3.0 | contact | | 連絡先情報 | | license | | ライセンス情報 | -### title +### info > title + +WebAPI の総称を記載する。 + +* システム名やサービス名 + API のような命名を推奨する。 -WebAPI の総称を記載する。システム名やサービス名 + API のような命名とすることを推奨する。 -例. `X System API` + 良い例： + + ```yaml + info: + title: X System API + ``` -### description +### info > description Web API が提供する機能の概要・想定する利用者やユースケース・制約などを記載する。 -### version +### info > version この API 仕様のドキュメントのバージョンを記載する。アプリケーションのバージョン（git tag やリリースで管理するようなバージョン）とは別である。 -本規約の推奨は `major.minor` 形式である。 `0.1 `固定で開発を進め、サービスのリリース時に `1.0` とし、その後の項目やオプション、パスの追加ごとに `1.1` などインクリメントしていく。もし他チームへのドキュメントの頻繁な共有が必要だれば、`1.0` のかわりに `2023.03.26` といった形式も許容する。 +* `major.minor` 形式を推奨する。 +`0.1 `固定で開発を進め、サービスのリリース時に `1.0` とし、その後の項目やオプション、パスの追加ごとにマイナーバージョンをインクリメントしていく。 + + 良い例： + + ```yaml + info: + version: 1.0 + ``` + +* もし他チームへの API ドキュメントの頻繁な共有が必要であれば、`major.minor` の代わりに `YYYY.MM.DD` の日付形式も許容する。 + + 良い例： + + ```yaml + info: + version: 2023.03.26 + ``` ## servers Web API を提供するサーバの情報を記載する。 -`url`, `description` を必須項目とする。 -| フィールド名 | 必須 | 記載内容 | -| ------------ | :--: | ---------- | -| url | ○ | 対象の URL | -| description | ○ | 説明 | -| variables | | なし | - -ステージ（local, develop, staging など）が複数ある場合は各ステージ分の情報を記載する。 ただし LSUDs 向けの Web API 開発においては本番環境の URL を不用意に公開したくないケースが多く、記載は避けるべきである。 +* `url`, `description` を必須項目とする。 +* ステージ（local, develop, staging など）が複数ある場合は各ステージ分の情報を記載する。 +* SSKDs 向けの Web API 開発においては本番環境の URL を不用意に公開したくないケースが多く、記載は避けるべきである。 良い例： @@ -130,7 +150,7 @@ servers: API の利用可能なエンドポイントと操作方法を記載する。 * API ごとに機能IDを定義している場合、`paths` 配下の各パスは機能 ID の昇順に定義する。 -* URLパスが複数の単語からなる場合、ケバブケースで表現する。 +* URL パスが複数の単語からなる場合、ケバブケースで表現する。 * HTTP メソッドは `GET`, `POST`, `PUT`, `PATCH`, `DELETE` の順に定義する。 良い例： @@ -157,19 +177,19 @@ API の利用可能なエンドポイントと操作方法を記載する。 * HTTPメソッドの配下に定義されるオペレーションオブジェクトは、下記の項目を必須項目とする。 -| フィールド名 | 必須 | 記載内容 | -| ------------ | :--: | ---------------------------------------- | -| tags | ○ | API の論理的なグループ | -| operationId | ○ | API の利用可能なエンドポイントと操作方法 | -| summary | ○ | API の操作概要 | -| description | | API の振る舞いの詳細や注意点を記載する。 | -| parameters | | API のリクエストパラメータ | -| requestBody | | API のリクエストボディ | -| response | ○ | API のレスポンス | -| security | | | + | フィールド名 | 必須 | 記載内容 | + | ------------ | :--: | ---------------------------------------- | + | tags | ○ | API の論理的なグループ | + | operationId | ○ | API の利用可能なエンドポイントと操作方法 | + | summary | ○ | API の操作概要 | + | description | | API の振る舞いの詳細や注意点を記載する。 | + | parameters | | API のリクエストパラメータ | + | requestBody | | API のリクエストボディ | + | response | ○ | API のレスポンス | + | security | | API のセキュリティ機構 | -### tags +### paths > tags API の論理的なグループを指定する。 @@ -227,7 +247,7 @@ API の論理的なグループを指定する。 ... ``` -### operationId +### paths > operationId API を識別するための一意な文字列を記載する。 @@ -245,15 +265,26 @@ API を識別するための一意な文字列を記載する。 /products/{product_id}: put: operationId: put-products-product-id + ... ``` -### summery + 良い例： + + ```yaml + paths: + /users/me: + get: + operationId: get_users_me + ... + ``` + +### paths > summary API の操作概要を記載する。 * 機能 ID や機能名があるのであれば記載する。 - 良い例 + 良い例： ```yaml paths: @@ -262,12 +293,12 @@ API の操作概要を記載する。 summary: API-001 ユーザアカウント取得 ``` -### description +### paths > description APIの振る舞いの詳細や注意点を記載する。 別途参照させるべき設計書があるのであれば、設計書へのリンクを記載しても良い。 -### parameters +### paths > parameters API のリクエストパラメータ（パスパラメータ、クエリパラメータ、ヘッダ）を記載する。 @@ -276,14 +307,14 @@ API のリクエストパラメータ（パスパラメータ、クエリパラ * クエリパラメータはスネークケースで表現する。 * ヘッダはハイフンを区切り文字とするパスカルケースで表現する。 - -### requestBody +### paths > requestBody API のリクエストボディを記載する。 -* リクエストボディを記載する。仕様の[describing-request-body](https://swagger.io/docs/specification/describing-request-body/)の章にある通り、リクエストボディはPOST、PUT、PATCHで使用され、GET、DELETE、HEADには利用できない -* requestBodyの定義は、components/requestBodiesで宣言し、 `$refs` で参照する -* requestBodyの命名は、 `Req` というプレフィクスと、 `Body` というサフィックスで終える必要がある +* リクエストボディを記載する。 + 標準仕様の [describing-request-body](https://swagger.io/docs/specification/describing-request-body/) の章にも記載がある通り、リクエストボディは `POST`、`PUT`、`PATCH` で使用され、`GET`、`DELETE`、`HEAD` には使用できない。 +* requestBodyの定義は、`components/requestBodies` で宣言し、`$refs` で参照する。 +* requestBodyの命名は、`Req` というプレフィクスと、`Body` というサフィックスで終える必要がある。 ```yaml paths: @@ -295,12 +326,12 @@ paths: ... ``` -### responses +### paths > responses API のレスポンスを記載する。 * OpenAPI ドキュメントからソースコードを自動生成する際に生成されるのクラスや構造体の命名をコントロールしたい場合などにおいては、スキーマ定義は `components` オブジェクトとして任意の名称で定義し `$ref` で参照する。 -スキーマ定義の名称は、全体で統一された命名ルールを定めること。（例. `operation_id` をアッパーキャメルケースへ変換の上、プレフィックスに `Res` を付与） +* スキーマ定義の名称は、全体で統一された命名ルールを定めること。（例. `operation_id` をアッパーキャメルケースへ変換の上、プレフィックスに `Res` を付与） * `schema` オブジェクトの `type` は `object` を指定する。 * 異常系（`4xx`, `5xx`）の HTTP ステータスコードに対応するレスポンス定義は設計者が個別に定義するのではなく、事前に共通的なレスポンスオブジェクトを定義し `$ref` で参照することが望ましい。 ​ @@ -341,16 +372,19 @@ components: ... ``` -### security +### paths > security -APIレベルの認証方式の設定だが、ルートレベルのsecurityで定義済みであるため、通常設定しない。 +APIの認証方式を記載する。 -ヘルスチェックのような認証を通す必要がないAPIのみ、上書きで定義する。 +* 通常はルートレベルの `security` でAPI共通的な認証方式を設定し、個々のAPIで個別に設定は行わない。 +* ヘルスチェックのような認証を通す必要がないAPIのみ、上書きで定義する。 -```yml -# 認証しない場合のみ個別で定義する -security: [] -``` + 良い例； + + ```yaml + # 認証しない場合のみ個別で定義する + security: [] + ``` ## components @@ -358,7 +392,7 @@ security: [] API 定義で利用する共通のデータモデルを定義 ​ -```yml +```yaml components: schemas: ... parameters: ... @@ -453,7 +487,7 @@ components: レスポンスの先頭には複数のエンドポイントで横断的に用いるモデルを定義する。例えば、ステータスコード400~500系のエラーモデルがある。 ​ -```yml +```yaml components: schemas: ProblemDetailError: @@ -478,7 +512,7 @@ components: ​ 正常系のレスポンスの例としてはファイルアップロード・ダウンロードなどが該当する。個別のアプリケーション要件でブレが少ないと複数のエンドポイントで用いられる場合に定義する。オブジェクトのスキーマは、schemasに切り出して定義し、コード生成ツールのために型情報を付与させる。 -```yml +```yaml components: schemas: SignedURL: @@ -514,7 +548,7 @@ components: それらの後に、paths登場順にエンドポイント固有のレスポンスを定義する。レスポンスオブジェクトのスキーマは、schemasに切り出して定義する。 -```yml +```yaml components: schemas: RespPostProductsSchema: @@ -554,7 +588,7 @@ API 共通で利用するパラメータ（パスパラメータ、クエリパ * 命名は クエリパラメータ名に `Query` というプレフィクスを付与する形式を推奨する。 -```yml +```yaml paths: get: /products: @@ -576,7 +610,7 @@ parameters: * API 全体で利用可能な共通のリクエストヘッダを定義する。 * 命名は ヘッダ名に `Header` というプレフィクスを付与する形式を推奨する。 -```yml +```yaml paths: post: /products: @@ -599,7 +633,7 @@ components: * 命名は Cookie パラメータ名に `Cookie` というプレフィクスを付与する形式を推奨する。 * Cookie 認証を定義する場合は、`APIKey` を利用すること。 -```yml +```yaml paths: get: /products: @@ -623,7 +657,7 @@ API 共通で利用するレスポンスヘッダを記載する。 * 命名は ヘッダ名からハイフンを除去した形式を推奨する。 -```yml +```yaml paths: get: /products: @@ -646,7 +680,7 @@ components: 標準で用いるAPI認証の定義を行う。 -```yml +```yaml # Bearer トークによる認証 securitySchemes: BearerAuth: @@ -690,7 +724,7 @@ securitySchemes: 業務システムのWeb APIで認証が全く存在しないことは考えにくいため、本規約ではルートレベルで認証を設定し、漏れをなくす。 -```yml +```yaml # 認証設定方法 (デフォルトで設定済みの為不要) security: - Bearer: [] From 68ae3dc8def240492121aeadbadd742dbbdce51b Mon Sep 17 00:00:00 2001 From: Hiroki Takeda Date: Fri, 19 Jan 2024 14:47:41 +0900 Subject: [PATCH 2/2] Format tags, security and externalDocs --- .../OpenAPI_Specification_3.0.3.md | 138 +++++++++--------- 1 file changed, 73 insertions(+), 65 deletions(-) diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index eb06e57a..d27e547f 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -81,7 +81,7 @@ openapi: 3.0 WebAPI の総称を記載する。 -* システム名やサービス名 + API のような命名を推奨する。 +- システム名やサービス名 + API のような命名を推奨する。 良い例： @@ -98,7 +98,7 @@ Web API が提供する機能の概要・想定する利用者やユースケー この API 仕様のドキュメントのバージョンを記載する。アプリケーションのバージョン（git tag やリリースで管理するようなバージョン）とは別である。 -* `major.minor` 形式を推奨する。 +- `major.minor` 形式を推奨する。 `0.1 `固定で開発を進め、サービスのリリース時に `1.0` とし、その後の項目やオプション、パスの追加ごとにマイナーバージョンをインクリメントしていく。 良い例： @@ -108,7 +108,7 @@ Web API が提供する機能の概要・想定する利用者やユースケー version: 1.0 ``` -* もし他チームへの API ドキュメントの頻繁な共有が必要であれば、`major.minor` の代わりに `YYYY.MM.DD` の日付形式も許容する。 +- もし他チームへの API ドキュメントの頻繁な共有が必要であれば、`major.minor` の代わりに `YYYY.MM.DD` の日付形式も許容する。 良い例： @@ -121,9 +121,9 @@ Web API が提供する機能の概要・想定する利用者やユースケー Web API を提供するサーバの情報を記載する。 -* `url`, `description` を必須項目とする。 -* ステージ（local, develop, staging など）が複数ある場合は各ステージ分の情報を記載する。 -* SSKDs 向けの Web API 開発においては本番環境の URL を不用意に公開したくないケースが多く、記載は避けるべきである。 +- `url`, `description` を必須項目とする。 +- ステージ（local, develop, staging など）が複数ある場合は各ステージ分の情報を記載する。 +- SSKDs 向けの Web API 開発においては本番環境の URL を不用意に公開したくないケースが多く、記載は避けるべきである。 良い例： @@ -149,9 +149,9 @@ servers: API の利用可能なエンドポイントと操作方法を記載する。 -* API ごとに機能IDを定義している場合、`paths` 配下の各パスは機能 ID の昇順に定義する。 -* URL パスが複数の単語からなる場合、ケバブケースで表現する。 -* HTTP メソッドは `GET`, `POST`, `PUT`, `PATCH`, `DELETE` の順に定義する。 +- API ごとに機能IDを定義している場合、`paths` 配下の各パスは機能 ID の昇順に定義する。 +- URL パスが複数の単語からなる場合、ケバブケースで表現する。 +- HTTP メソッドは `GET`, `POST`, `PUT`, `PATCH`, `DELETE` の順に定義する。 良い例： @@ -175,7 +175,7 @@ API の利用可能なエンドポイントと操作方法を記載する。 ... ``` -* HTTPメソッドの配下に定義されるオペレーションオブジェクトは、下記の項目を必須項目とする。 +- HTTPメソッドの配下に定義されるオペレーションオブジェクトは、下記の項目を必須項目とする。 | フィールド名 | 必須 | 記載内容 | | ------------ | :--: | ---------------------------------------- | @@ -193,7 +193,7 @@ API の利用可能なエンドポイントと操作方法を記載する。 API の論理的なグループを指定する。 -* タグオブジェクトとして事前定義したタグの中から選択すること。 +- タグオブジェクトとして事前定義したタグの中から選択すること。 良い例： @@ -221,7 +221,7 @@ API の論理的なグループを指定する。 tags: [] ``` -* 1 API につき 1つのタグを指定すること。 +- 1 API につき 1つのタグを指定すること。 良い例： @@ -251,7 +251,7 @@ API の論理的なグループを指定する。 API を識別するための一意な文字列を記載する。 -* HTTP メソッドとURLパスをアッパーキャメルケースで表現する。 +- HTTP メソッドとURLパスをアッパーキャメルケースで表現する。 ただしOpenAPI ドキュメントのエディタとして広く使用されるStoplightが提供する[Linter](https://docs.stoplight.io/docs/spectral/674b27b261c3c-overview)の定義としてケバブケースが標準になっているため、Stoplightを使用する場合はケバブケースで表現しても良い。 良い例： @@ -282,7 +282,7 @@ API を識別するための一意な文字列を記載する。 API の操作概要を記載する。 -* 機能 ID や機能名があるのであれば記載する。 +- 機能 ID や機能名があるのであれば記載する。 良い例： @@ -302,19 +302,19 @@ APIの振る舞いの詳細や注意点を記載する。 API のリクエストパラメータ（パスパラメータ、クエリパラメータ、ヘッダ）を記載する。 -* HTTP メソッドが `GET`, `DELETE` の場合にのみ指定する。 -* パスパラメータはスネークケースで表現する。 -* クエリパラメータはスネークケースで表現する。 -* ヘッダはハイフンを区切り文字とするパスカルケースで表現する。 +- HTTP メソッドが `GET`, `DELETE` の場合にのみ指定する。 +- パスパラメータはスネークケースで表現する。 +- クエリパラメータはスネークケースで表現する。 +- ヘッダはハイフンを区切り文字とするパスカルケースで表現する。 ### paths > requestBody API のリクエストボディを記載する。 -* リクエストボディを記載する。 +- リクエストボディを記載する。 標準仕様の [describing-request-body](https://swagger.io/docs/specification/describing-request-body/) の章にも記載がある通り、リクエストボディは `POST`、`PUT`、`PATCH` で使用され、`GET`、`DELETE`、`HEAD` には使用できない。 -* requestBodyの定義は、`components/requestBodies` で宣言し、`$refs` で参照する。 -* requestBodyの命名は、`Req` というプレフィクスと、`Body` というサフィックスで終える必要がある。 +- requestBodyの定義は、`components/requestBodies` で宣言し、`$refs` で参照する。 +- requestBodyの命名は、`Req` というプレフィクスと、`Body` というサフィックスで終える必要がある。 ```yaml paths: @@ -330,10 +330,10 @@ paths: API のレスポンスを記載する。 -* OpenAPI ドキュメントからソースコードを自動生成する際に生成されるのクラスや構造体の命名をコントロールしたい場合などにおいては、スキーマ定義は `components` オブジェクトとして任意の名称で定義し `$ref` で参照する。 -* スキーマ定義の名称は、全体で統一された命名ルールを定めること。（例. `operation_id` をアッパーキャメルケースへ変換の上、プレフィックスに `Res` を付与） -* `schema` オブジェクトの `type` は `object` を指定する。 -* 異常系（`4xx`, `5xx`）の HTTP ステータスコードに対応するレスポンス定義は設計者が個別に定義するのではなく、事前に共通的なレスポンスオブジェクトを定義し `$ref` で参照することが望ましい。 +- OpenAPI ドキュメントからソースコードを自動生成する際に生成されるのクラスや構造体の命名をコントロールしたい場合などにおいては、スキーマ定義は `components` オブジェクトとして任意の名称で定義し `$ref` で参照する。 +- スキーマ定義の名称は、全体で統一された命名ルールを定めること。（例. `operation_id` をアッパーキャメルケースへ変換の上、プレフィックスに `Res` を付与） +- `schema` オブジェクトの `type` は `object` を指定する。 +- 異常系（`4xx`, `5xx`）の HTTP ステータスコードに対応するレスポンス定義は設計者が個別に定義するのではなく、事前に共通的なレスポンスオブジェクトを定義し `$ref` で参照することが望ましい。 ​ ```yaml @@ -376,8 +376,8 @@ components: APIの認証方式を記載する。 -* 通常はルートレベルの `security` でAPI共通的な認証方式を設定し、個々のAPIで個別に設定は行わない。 -* ヘルスチェックのような認証を通す必要がないAPIのみ、上書きで定義する。 +- 通常はルートレベルの `security` でAPI共通的な認証方式を設定し、個々のAPIで個別に設定は行わない。 +- ヘルスチェックのような認証を通す必要がないAPIのみ、上書きで定義する。 良い例； @@ -408,8 +408,8 @@ components: ### schemas -* API 定義で共通で利用するスキーマを定義 -* 規約 +- API 定義で共通で利用するスキーマを定義 +- 規約 * [ ] リソース名はアッパーキャメルケースで定義 * [ ] リソース名は単数形で定義 * [ ] `type` に複数の型定義の指定不可 @@ -435,9 +435,9 @@ Pagination: スキーマ定義のモデルは以下3種類 -* [リクエストボディ](#リクエストボディ) -* [レスポンス](#レスポンス) -* [リソース](#リソース) +- [リクエストボディ](#リクエストボディ) +- [レスポンス](#レスポンス) +- [リソース](#リソース) ```yaml # ソート順は以下の通り @@ -462,10 +462,10 @@ components: #### requestBodies(components) -* `requestBody` 直下の `required` は必須で `true` を指定する -* OpenAPI ドキュメントからソースコードを自動生成する際に生成されるのクラスや構造体の命名をコントロールしたい場合などにおいては、スキーマ定義は `component` オブジェクトとして任意の名称で定義し `$ref` で参照する。 +- `requestBody` 直下の `required` は必須で `true` を指定する +- OpenAPI ドキュメントからソースコードを自動生成する際に生成されるのクラスや構造体の命名をコントロールしたい場合などにおいては、スキーマ定義は `component` オブジェクトとして任意の名称で定義し `$ref` で参照する。 スキーマ定義の名称は、全体で統一された命名ルールを定めること。（例. `operation_id` をアッパーキャメルケースへ変換の上、プレフィックスに `Req` を付与） -* `schema` オブジェクトの `type` は `object` を指定する。 +- `schema` オブジェクトの `type` は `object` を指定する。 ```yaml components: @@ -579,13 +579,13 @@ API 共通で利用するパラメータ（パスパラメータ、クエリパ ##### パスパラメータ -* API 全体で利用されるパスパラメータが必要なケースが想定されないため、原則定義しない。 +- API 全体で利用されるパスパラメータが必要なケースが想定されないため、原則定義しない。 特定リソースの操作（例えば更新と削除）を行う際のリソースIDはパスパラメータとして再利用できるが、コンフリクトを避けるため原則共通化は行わない。 ##### クエリパラメータ -* API 全体で利用可能な共通のクエリパラメータを定義する （例: 検索数のlimit, offset） -* 命名は クエリパラメータ名に `Query` というプレフィクスを付与する形式を推奨する。 +- API 全体で利用可能な共通のクエリパラメータを定義する （例: 検索数のlimit, offset） +- 命名は クエリパラメータ名に `Query` というプレフィクスを付与する形式を推奨する。 ```yaml @@ -607,8 +607,8 @@ parameters: ##### ヘッダパラメータ -* API 全体で利用可能な共通のリクエストヘッダを定義する。 -* 命名は ヘッダ名に `Header` というプレフィクスを付与する形式を推奨する。 +- API 全体で利用可能な共通のリクエストヘッダを定義する。 +- 命名は ヘッダ名に `Header` というプレフィクスを付与する形式を推奨する。 ```yaml paths: @@ -629,9 +629,9 @@ components: ##### Cookie パラメータ -* API 全体で利用可能な共通のCookieパラメータを定義する。（例: CSRF用のトークン） -* 命名は Cookie パラメータ名に `Cookie` というプレフィクスを付与する形式を推奨する。 -* Cookie 認証を定義する場合は、`APIKey` を利用すること。 +- API 全体で利用可能な共通のCookieパラメータを定義する。（例: CSRF用のトークン） +- 命名は Cookie パラメータ名に `Cookie` というプレフィクスを付与する形式を推奨する。 +- Cookie 認証を定義する場合は、`APIKey` を利用すること。 ```yaml paths: @@ -655,7 +655,7 @@ components: API 共通で利用するレスポンスヘッダを記載する。 -* 命名は ヘッダ名からハイフンを除去した形式を推奨する。 +- 命名は ヘッダ名からハイフンを除去した形式を推奨する。 ```yaml paths: @@ -720,54 +720,54 @@ securitySchemes: ## security -ルートレベルのsecurityを定義すると、全APIに共通で適用される。 +全APIに共通で適用されるセキュリティ設定を定義する。 +業務システムの Web API において 認証が全く存在しないケースは考えにくいため、本規約ではルートレベルで認証を設定し、個々のAPIへの適応漏れをなくす。 -業務システムのWeb APIで認証が全く存在しないことは考えにくいため、本規約ではルートレベルで認証を設定し、漏れをなくす。 +良い例： ```yaml -# 認証設定方法 (デフォルトで設定済みの為不要) security: - Bearer: [] ``` -ヘルスチェックなどAPI種別によって認証が不要な場合がある。それらに対しては個別に、認証情報を上書き定義する。 - ## tags -タグを用いて、API 操作をグループ化することができる。ドキュメントやツールにとって非常に重要であるため、 **必須** で指定する。 +API を論理的にグループ化するためのタグを定義する。ドキュメントやツールにとって重要であるため、 **必須** で指定する。 + +- `name`, `description` を必須項目とする。 +- **単数形** で、小文字かつ半角スペース区切りで記載する。 + 半角スペース区切りで記載する理由は　HTML ドキュメントで参照する場合の可読性を上げるためである。 +- コード生成で利用される（Go においてはパッケージ、 TypeScriptにおいてはクラスに相当する）ため、シンプルな命名にする。 -- Swagger UI（HTML ドキュメント）の順序を制御できる - - 未指定の場合は、登場順で生成されてしまう -- 命名は、 **単数形** で、小文字かつ半角スペース区切り で記載する - - コード生成で利用され、Go ではパッケージ名や TypeScript の Class 単位となるため、シンプルな命名にする - - HTML ドキュメントで参照する場合の可読性を上げるため、単語を半角スペース区切りとする -- タグごとに `description` も必須で記載する +良い例： ```yaml -# NG tags: - name: product description: 製品 - - name: store - description: 店舗 - name: user account description: ユーザーアカウント +``` -# NG +悪い例： + +```yaml tags: - name: products - - name: stores + description: 製品 - name: user_account - - name: UserAccount + description: ユーザーアカウント ``` - ## externalDocs -Schema定義, Paths配下の各API定義, OASのトップ階層などで、参照情報としてのURLを指定し表示が可能。ただし、`description` にてリンクURLを記載する方が、複数リンクを指定可能であるなど自由度が高く使いやすい。そのため、参照先URLリンクの記載には、`externalDocs` ではなく `description` の利用を推奨する。 +参照情報としてのURLの記載が可能。 +ただし、`description` にて参考情報となるURLを記載する方が、複数リンクを指定可能であるなど自由度が高く使いやすい。そのため `externalDocs` は利用せず `description` の利用を推奨する。 + + +良い例： ```yaml -# 推奨 info: description: |- Some useful links: @@ -780,6 +780,14 @@ externalDocs: url: http://swagger.io ``` +悪い例： + +```yaml +externalDocs: + description: Find out more about Swagger + url: http://swagger.io +``` + # 設計上のポイント ## ファイルアップロード