diff --git a/documents/forOpenAPISpecification/API_Design.md b/documents/forOpenAPISpecification/API_Design.md deleted file mode 100644 index f93fd98a..00000000 --- a/documents/forOpenAPISpecification/API_Design.md +++ /dev/null @@ -1,57 +0,0 @@ -# Web API 設計標準 - -OpenAPI Specification 規約を利用するに当たり、想定する Web API の設計ルールをまとめる。このルールに必ずしも準じる必要は無いが、このような設計を暗黙的に考慮し OpenAPI Specification 規約を作成している。 - -## HTTP メソッド - -実現したい操作により、以下のような使い分けを想定する。HEAD（リソースの存在チェック）、GET（参照）、POST（新規作成）、PUT（更新）、PATCH（一部更新）、DELETE（削除）。 - -## HTTP ステータス - -[RFC 7231](https://tools.ietf.org/html/rfc7231#section-6)で定義されているレスポンスステータスコードを利用します。 - -[RFC9205](https://datatracker.ietf.org/doc/html/rfc9205)（[日本語訳](https://tex2e.github.io/rfc-translater/html/rfc9205.html#section-4.6)）の方針に原則則る。ユースケース別に利用すべき HTTP ステータスコードを記載します。 - -### 共通 - -- バリデーションエラー：`400 Bad Request` -- 業務エラー：`400 Bad Request` -- 認証エラー：`401 Unauthorized` -- 認可エラー：`403 Forbidden` -- システムエラー：`500 Internal Server Error` - -### GET - -- 正常系：`200 OK` - - 検索系 API で結果 0 件の場合も、 `200 OK` を返すとする -- パスキー検索系 API で対象リソースが存在しないエラー：`404 Not Found` - -### POST - -- 正常系（同期）：`201 Created` -- 正常系（非同期）：`202 Accepted` -- 一意制約違反エラー：`409 Conflict` -- 親リソースが存在しないエラー：`404 Not Found` - -### PUT - -- 正常系（同期）：`200 OK` -- 正常系（非同期）：`202 Accepted` -- 対象リソースが存在しないエラー：`404 Not Found` - -### DELETE - -- 正常系：`204 No Content` - - もし、削除した項目の情報を応答する場合は `200 OK` とする -- 対象リソースが存在しないエラー：`404 Not Found` - -## API バージョン管理 - -- /v1, /v2 といったパスで表現する -- 型名変更、必須パラメータの追加、レスポンスの桁数変更、などをするときはバージョンを上げることを検討する - -## パラメータの命名 - -boolean 型である場合、 `[a-zA-Z0-9-_]+_flag` という命名は非推奨とする。 - -`is_[a-zA-Z0-9-_]+` や `has_[a-zA-Z0-9-_]+` などの命名を代わりに検討する diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md index 87fde9c4..ca69194b 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md @@ -18,9 +18,26 @@ head: [OpenAPI Specification 2.0（Swagger, OAS2）](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md)定義についてのコーディング規約をまとめます。より新しいバージョンとして OAS 3.0.3 規約（作成中）がありますので、ご注意ください。 -本規約の[前提条件](prerequisite.md)に従い作成されています。ToC 向けの LSUDs（Large Set of Unknown Developers）な Web API にはマッチしない可能性があります。 - -Web API 自体の設計については範囲外としますが、[API 設計標準](API_Design.md)に利用するステータスコードなどは記載しています。 +# 前提条件 + +本規約は以下の前提で作成されたものである。。ToC 向けの LSUDs（Large Set of Unknown Developers）な Web API にはマッチしない可能性があります。 + +- 業務システム向けの Web API 提供 + - サードパーティ向けに広く開発する Web API ではなく、限られたクライアントやシステムと連携すること + - いわゆる、LSUDs（Large Set of Unknown Developers）ではなく、SSKDs（Small Set of Known Developers）を対象とする +- RESTish な Web API + - 原理的な REST を必ずしも守る必要はないが、例えば HTTP メソッドは、参照は GET、登録は POST、更新は PUT や PATCH、削除は DELETE で使い分けていたり、Web API の要求が成功すれば 200（OK）、204（No Content）を返し、リソースが無ければ 404（Not Found）、操作に失敗すれば 500 系のエラーを返すといったことを指す + - 本規約を利用するに当たり必須条件ではないが、定義例などはそれに基づいて記載しているので注意する +- スキーマファースト + - OpenAPI Specification の定義ファイルを駆動に、クライアント・サーバサイドのコード生成やモック時の利用に用い、高速な Web API 開発につなげることを前提とする + - Python における、FastAPI・Django REST Framework のように、アプリケーションコードから OpenAPI document を自動生成する開発手法も存在するが、本規約はこれは想定しない + - 定義ファイルの完成度はできるかぎり高め、コード生成やドキュメントの価値を高める + - OAS 定義からコードを生成し、通常は記載した型・項目長・最大～最小・enum・必須定義・正規表現フォーマットでバリデーションを行い、カバーできない部分のバリデーションをアプリケーション固有ロジックとして実装する方針とする。例えば、複数項目間のチェックや DB を確認しないと行えないチェックである + - ドキュメントとしての価値を高めるため、その API 呼び出しで発生しうる全ての HTTP ステータスコードを記載する + - API の振る舞いを読み手に伝えるものとして、どのような異常系があるかは有用な場合が多いからである +- JavaScript/TypeScript、Java、Go のエコシステムがターゲット + - OpenAPI Specification は広く受け入れられており、コレに対応する様々なツールやフレームワークといったエコシステムがあり、中には定義された設定がうまく認識されない場合がある。本規約では対応していないツールが多い場合、特定の記法を非推奨とすることがあり、同時にその理由も説明する + - 全ての言語・フレームワーク・ツールの対応状況は調査しきれていないため、利用するプロダクトの対応状況は利用者側で確認をお願いする # 免責事項 @@ -30,9 +47,136 @@ Web API 自体の設計については範囲外としますが、[API 設計標 ::: -# ファイルフォーマット +# API設計 + +Web API の設計自体はこの規約の範囲外であるが、簡易的な方針を示す。必要に応じて参考にされたい。 + +## HTTP メソッド + +実現したい操作により、以下のような使い分けを想定する。HEAD（リソースの存在チェック）、GET（参照）、POST（新規作成）、PUT（更新）、PATCH（一部更新）、DELETE（削除）。 + +## HTTP ステータス + +[RFC 7231](https://tools.ietf.org/html/rfc7231#section-6)で定義されているレスポンスステータスコードを利用します。 + +[RFC9205](https://datatracker.ietf.org/doc/html/rfc9205)（[日本語訳](https://tex2e.github.io/rfc-translater/html/rfc9205.html#section-4.6)）の方針に原則則る。ユースケース別に利用すべき HTTP ステータスコードを記載します。 + +### 共通 + +- バリデーションエラー：`400 Bad Request` +- 業務エラー：`400 Bad Request` +- 認証エラー：`401 Unauthorized` +- 認可エラー：`403 Forbidden` +- システムエラー：`500 Internal Server Error` + +### GET + +- 正常系：`200 OK` + - 検索系 API で結果 0 件の場合も、 `200 OK` を返すとする +- パスキー検索系 API で対象リソースが存在しないエラー：`404 Not Found` + +### POST + +- 正常系（同期）：`201 Created` +- 正常系（非同期）：`202 Accepted` +- 一意制約違反エラー：`409 Conflict` +- 親リソースが存在しないエラー：`404 Not Found` + +### PUT + +- 正常系（同期）：`200 OK` +- 正常系（非同期）：`202 Accepted` +- 対象リソースが存在しないエラー：`404 Not Found` + +### DELETE + +- 正常系：`204 No Content` + - もし、削除した項目の情報を応答する場合は `200 OK` とする +- 対象リソースが存在しないエラー：`404 Not Found` + +## API バージョン管理 + +- /v1, /v2 といったパスで表現する +- 型名変更、必須パラメータの追加、レスポンスの桁数変更、などをするときはバージョンを上げることを検討する + +## パラメータの命名 + +boolean 型である場合、 `[a-zA-Z0-9-_]+_flag` という命名は非推奨とする。 + +`is_[a-zA-Z0-9-_]+` や `has_[a-zA-Z0-9-_]+` などの命名を代わりに検討する + +# YAMLファイルフォーマット + +OpenAPI ドキュメントは JSON 形式、YAML 形式いずれかのフォーマットで記載できるが **YAML 形式** を利用する。理由として、JSON と比較して YAML は視覚的に見やすく、レビューや差分管理が行いやすいためである。 + +## ファイル名 + +ファイルの拡張子は `yaml` とする。通常ファイル名は `api.yaml` や `swagger.yaml`（v2 の場合） を推奨する。 -[ファイルフォーマット規約](file_standards.md)に準じる。 +もし、複数の Swagger 定義を管理するため区別したい場合は `${service}_api.yaml` とする。 + +`${service}` にはサービス名を指定する + +## YAML バージョン + +[YAML v1.2](https://yaml.org/spec/1.2.2/#61-indentation-spaces)を用いる。 + +## ファイルレイアウト + +- ファイルの最終行には空行を入れる +- 文字コードは UTF-8 とする +- タブは半角スペース 2 つとする + +## クォート + +クォートは可読性を上げるために、できる限り利用しない。利用する場合はダブルクォートを利用する。 + +```yaml +# OK +description: 何かしらの説明 + +# NG（クォートでのラップは不要） +description: '何かしらの説明' +description: "何かしらの説明" +``` + +以下の場合は必須で利用する + +- 文字列として認識させる必要のある数字（"0123"） +- 60 進数と認識させたくない場合（"12:34"） +- Bool として認識させたくない（"true", "false", "yes", "no", "y", "n", "on", "off"） +- `#` で始まる文字列（`#` はコメントを示す記号のためである。例: `#/definitions/Users`） + +## YAML 配列スタイル + +- 複数項目を指定する場合は、 **Flow style(配列スキーム)** を用いることを推奨する + + ```yaml + # OK（推奨: 配列リテラル構文） + required: [user_id, user_name, account_type, register_at] + + # NG（非推奨: リスト構文） + required: + - user_id + - user_name + - account_type + - register_at + ``` + + - YAML は項目定義がネストすることで縦長な定義になりやすい。情報密度を上げるために配列リテラルを推奨する + +## 改行の表現 + +改行を含む場合は、パイプ（ブロックスカラー） `|` を用いる + +```yaml +description: | + 説明文1 + 説明文2 + - 箇条書き1 + - 箇条書き2 + - 箇条書き3 +``` # 要素規約 diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index 3b9c6a90..4536314c 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -19,8 +19,28 @@ head: 本ドキュメントは [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) にステータスコード等の標準を記載しているため、必要に応じて参考にされたい。 +# 前提条件 + +本規約は以下の前提条件に基づいて作成されており、ToC 向けの LSUDs（Large Set of Unknown Developers）向けの Web API には適合しない場合もあるのでご留意いただきたい。 + +- 業務システム向けの Web API 提供 + - サードパーティ向けに広く開発する Web API ではなく、限られたクライアントやシステムと連携すること + - いわゆる、LSUDs（Large Set of Unknown Developers）ではなく、SSKDs（Small Set of Known Developers）を対象とする +- RESTish な Web API + - 原理的な REST を必ずしも守る必要はないが、例えば HTTP メソッドは、参照は GET、登録は POST、更新は PUT や PATCH、削除は DELETE で使い分けていたり、Web API の要求が成功すれば 200（OK）、204（No Content）を返し、リソースが無ければ 404（Not Found）、操作に失敗すれば 500 系のエラーを返すといったことを指す + - 本規約を利用するに当たり必須条件ではないが、定義例などはそれに基づいて記載しているので注意する +- スキーマファースト + - OpenAPI Specification の定義ファイルを駆動に、クライアント・サーバサイドのコード生成やモック時の利用に用い、高速な Web API 開発につなげることを前提とする + - Python における、FastAPI・Django REST Framework のように、アプリケーションコードから OpenAPI document を自動生成する開発手法も存在するが、本規約はこれは想定しない + - 定義ファイルの完成度はできるかぎり高め、コード生成やドキュメントの価値を高める + - OAS 定義からコードを生成し、通常は記載した型・項目長・最大～最小・enum・必須定義・正規表現フォーマットでバリデーションを行い、カバーできない部分のバリデーションをアプリケーション固有ロジックとして実装する方針とする。例えば、複数項目間のチェックや DB を確認しないと行えないチェックである + - ドキュメントとしての価値を高めるため、その API 呼び出しで発生しうる全ての HTTP ステータスコードを記載する + - API の振る舞いを読み手に伝えるものとして、どのような異常系があるかは有用な場合が多いからである +- JavaScript/TypeScript、Java、Go のエコシステムがターゲット + - OpenAPI Specification は広く受け入れられており、コレに対応する様々なツールやフレームワークといったエコシステムがあり、中には定義された設定がうまく認識されない場合がある。本規約では対応していないツールが多い場合、特定の記法を非推奨とすることがあり、同時にその理由も説明する + - 全ての言語・フレームワーク・ツールの対応状況は調査しきれていないため、利用するプロダクトの対応状況は利用者側で確認をお願いする + +# 免責事項 ::: warning 有志で作成したドキュメントである @@ -28,11 +48,138 @@ Web API の設計自体はこの規約の範囲外であるが、[API 設計標 ::: -## ファイルフォーマット +# API設計 -[ファイルフォーマット規約](file_standards.md)に従う。 +Web API の設計自体はこの規約の範囲外であるが、簡易的な方針を示す。必要に応じて参考にされたい。 -## OpenAPI ドキュメントの構成要素 +## HTTP メソッド + +実現したい操作により、以下のような使い分けを想定する。HEAD（リソースの存在チェック）、GET（参照）、POST（新規作成）、PUT（更新）、PATCH（一部更新）、DELETE（削除）。 + +## HTTP ステータス + +[RFC 7231](https://tools.ietf.org/html/rfc7231#section-6)で定義されているレスポンスステータスコードを利用します。 + +[RFC9205](https://datatracker.ietf.org/doc/html/rfc9205)（[日本語訳](https://tex2e.github.io/rfc-translater/html/rfc9205.html#section-4.6)）の方針に原則則る。ユースケース別に利用すべき HTTP ステータスコードを記載します。 + +### 共通 + +- バリデーションエラー：`400 Bad Request` +- 業務エラー：`400 Bad Request` +- 認証エラー：`401 Unauthorized` +- 認可エラー：`403 Forbidden` +- システムエラー：`500 Internal Server Error` + +### GET + +- 正常系：`200 OK` + - 検索系 API で結果 0 件の場合も、 `200 OK` を返すとする +- パスキー検索系 API で対象リソースが存在しないエラー：`404 Not Found` + +### POST + +- 正常系（同期）：`201 Created` +- 正常系（非同期）：`202 Accepted` +- 一意制約違反エラー：`409 Conflict` +- 親リソースが存在しないエラー：`404 Not Found` + +### PUT + +- 正常系（同期）：`200 OK` +- 正常系（非同期）：`202 Accepted` +- 対象リソースが存在しないエラー：`404 Not Found` + +### DELETE + +- 正常系：`204 No Content` + - もし、削除した項目の情報を応答する場合は `200 OK` とする +- 対象リソースが存在しないエラー：`404 Not Found` + +## API バージョン管理 + +- /v1, /v2 といったパスで表現する +- 型名変更、必須パラメータの追加、レスポンスの桁数変更、などをするときはバージョンを上げることを検討する + +## パラメータの命名 + +boolean 型である場合、 `[a-zA-Z0-9-_]+_flag` という命名は非推奨とする。 + +`is_[a-zA-Z0-9-_]+` や `has_[a-zA-Z0-9-_]+` などの命名を代わりに検討する + +# YAMLファイルフォーマット + +OpenAPI ドキュメントは JSON 形式、YAML 形式いずれかのフォーマットで記載できるが **YAML 形式** を利用する。理由として、JSON と比較して YAML は視覚的に見やすく、レビューや差分管理が行いやすいためである。 + +## ファイル名 + +ファイルの拡張子は `yaml` とする。通常ファイル名は `api.yaml` や `swagger.yaml`（v2 の場合） を推奨する。 + +もし、複数の Swagger 定義を管理するため区別したい場合は `${service}_api.yaml` とする。 + +`${service}` にはサービス名を指定する + +## YAML バージョン + +[YAML v1.2](https://yaml.org/spec/1.2.2/#61-indentation-spaces)を用いる。 + +## ファイルレイアウト + +- ファイルの最終行には空行を入れる +- 文字コードは UTF-8 とする +- タブは半角スペース 2 つとする + +## クォート + +クォートは可読性を上げるために、できる限り利用しない。利用する場合はダブルクォートを利用する。 + +```yaml +# OK +description: 何かしらの説明 + +# NG（クォートでのラップは不要） +description: '何かしらの説明' +description: "何かしらの説明" +``` + +以下の場合は必須で利用する + +- 文字列として認識させる必要のある数字（"0123"） +- 60 進数と認識させたくない場合（"12:34"） +- Bool として認識させたくない（"true", "false", "yes", "no", "y", "n", "on", "off"） +- `#` で始まる文字列（`#` はコメントを示す記号のためである。例: `#/definitions/Users`） + +## YAML 配列スタイル + +- 複数項目を指定する場合は、 **Flow style(配列スキーム)** を用いることを推奨する + + ```yaml + # OK（推奨: 配列リテラル構文） + required: [user_id, user_name, account_type, register_at] + + # NG（非推奨: リスト構文） + required: + - user_id + - user_name + - account_type + - register_at + ``` + + - YAML は項目定義がネストすることで縦長な定義になりやすい。情報密度を上げるために配列リテラルを推奨する + +## 改行の表現 + +改行を含む場合は、パイプ（ブロックスカラー） `|` を用いる + +```yaml +description: | + 説明文1 + 説明文2 + - 箇条書き1 + - 箇条書き2 + - 箇条書き3 +``` + +# OpenAPI ドキュメントの構成要素 OpenAPI ドキュメントを構成する要素はオブジェクトと呼ばれ、ルートオブジェクトは以下の要素で構成される。 diff --git a/documents/forOpenAPISpecification/file_standards.md b/documents/forOpenAPISpecification/file_standards.md deleted file mode 100644 index a618043a..00000000 --- a/documents/forOpenAPISpecification/file_standards.md +++ /dev/null @@ -1,76 +0,0 @@ -# ファイルフォーマット規約 - -## フォーマット - -OpenAPI ドキュメントは JSON 形式、YAML 形式いずれかのフォーマットで記載できるが **YAML 形式** を利用する。 - -理由として、JSON と比較して YAML は視覚的に見やすく、レビューや差分管理が行いやすいためである。 - -## ファイル名 - -ファイルの拡張子は `yaml` とする。通常ファイル名は `api.yaml` や `swagger.yaml`（v2 の場合） を推奨する。 - -もし、複数の Swagger 定義を管理するため区別したい場合は `${service}_api.yaml` とする。 - -`${service}` にはサービス名を指定する - -## YAML バージョン - -[YAML v1.2](https://yaml.org/spec/1.2.2/#61-indentation-spaces)を用いる。 - -## ファイルレイアウト - -- ファイルの最終行には空行を入れる -- 文字コードは UTF-8 とする -- タブは半角スペース 2 つとする - -## クォート - -クォートは可読性を上げるために、できる限り利用しない。利用する場合はダブルクォートを利用する。 - -```yaml -# OK -description: 何かしらの説明 - -# NG（クォートでのラップは不要） -description: '何かしらの説明' -description: "何かしらの説明" -``` - -以下の場合は必須で利用する - -- 文字列として認識させる必要のある数字（"0123"） -- 60 進数と認識させたくない場合（"12:34"） -- Bool として認識させたくない（"true", "false", "yes", "no", "y", "n", "on", "off"） -- `#` で始まる文字列（`#` はコメントを示す記号のためである。例: `#/definitions/Users`） - -## YAML 配列スタイル - -- 複数項目を指定する場合は、 **Flow style(配列スキーム)** を用いることを推奨する - - ```yaml - # OK（推奨: 配列リテラル構文） - required: [user_id, user_name, account_type, register_at] - - # NG（非推奨: リスト構文） - required: - - user_id - - user_name - - account_type - - register_at - ``` - - - YAML は項目定義がネストすることで縦長な定義になりやすい。情報密度を上げるために配列リテラルを推奨する - -## 改行の表現 - -改行を含む場合は、パイプ（ブロックスカラー） `|` を用いる - -```yaml -description: | - 説明文1 - 説明文2 - - 箇条書き1 - - 箇条書き2 - - 箇条書き3 -``` diff --git a/documents/forOpenAPISpecification/prerequisite.md b/documents/forOpenAPISpecification/prerequisite.md deleted file mode 100644 index 932fc883..00000000 --- a/documents/forOpenAPISpecification/prerequisite.md +++ /dev/null @@ -1,22 +0,0 @@ -# 前提条件 - -本規約は以下の前提で作成されたものである。 - -- 業務システム向けの Web API 提供 - - サードパーティ向けに広く開発する Web API ではなく、限られたクライアントやシステムと連携すること - - いわゆる、LSUDs（Large Set of Unknown Developers）ではなく、SSKDs（Small Set of Known Developers）を対象とする - -* RESTish な Web API - - 原理的な REST を必ずしも守る必要はないが、例えば HTTP メソッドは、参照は GET、登録は POST、更新は PUT や PATCH、削除は DELETE で使い分けていたり、Web API の要求が成功すれば 200（OK）、204（No Content）を返し、リソースが無ければ 404（Not Found）、操作に失敗すれば 500 系のエラーを返すといったことを指す - - 本規約を利用するに当たり必須条件ではないが、定義例などはそれに基づいて記載しているので注意する - -- スキーマファースト - - OpenAPI Specification の定義ファイルを駆動に、クライアント・サーバサイドのコード生成やモック時の利用に用い、高速な Web API 開発につなげることを前提とする - - Python における、FastAPI・Django REST Framework のように、アプリケーションコードから OpenAPI document を自動生成する開発手法も存在するが、本規約はこれは想定しない - - 定義ファイルの完成度はできるかぎり高め、コード生成やドキュメントの価値を高める - - OAS 定義からコードを生成し、通常は記載した型・項目長・最大～最小・enum・必須定義・正規表現フォーマットでバリデーションを行い、カバーできない部分のバリデーションをアプリケーション固有ロジックとして実装する方針とする。例えば、複数項目間のチェックや DB を確認しないと行えないチェックである - - ドキュメントとしての価値を高めるため、その API 呼び出しで発生しうる全ての HTTP ステータスコードを記載する - - API の振る舞いを読み手に伝えるものとして、どのような異常系があるかは有用な場合が多いからである -- JavaScript/TypeScript、Java、Go のエコシステムがターゲット - - OpenAPI Specification は広く受け入れられており、コレに対応する様々なツールやフレームワークといったエコシステムがあり、中には定義された設定がうまく認識されない場合がある。本規約では対応していないツールが多い場合、特定の記法を非推奨とすることがあり、同時にその理由も説明する - - 全ての言語・フレームワーク・ツールの対応状況は調査しきれていないため、利用するプロダクトの対応状況は利用者側で確認をお願いする