From b4dd231431db7be4291660086c0b0dfff534c31f Mon Sep 17 00:00:00 2001 From: future-mano Date: Fri, 10 Nov 2023 14:58:29 +0900 Subject: [PATCH 1/2] =?UTF-8?q?=E5=89=8D=E6=8F=90=E6=9D=A1=E4=BB=B6?= =?UTF-8?q?=E3=82=92=E5=88=87=E3=82=8A=E5=87=BA=E3=81=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../OpenAPI_Specification_2.0.md | 19 +----------------- .../forOpenAPISpecification/prerequisite.md | 20 +++++++++++++++++++ 2 files changed, 21 insertions(+), 18 deletions(-) create mode 100644 documents/forOpenAPISpecification/prerequisite.md diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md index 2f8d1f73..1be39cb8 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md @@ -19,24 +19,7 @@ meta: ## 前提条件 -本規約は以下の前提で作成されたものである。 - -- 業務システム向けの Web API 提供 - - サードパーティ向けに広く開発する Web API ではなく、限られたクライアントやシステムと連携すること - - いわゆる、LSUDs（Large Set of Unknown Developers）ではなく、SSKDs（Small Set of Known Developers）を対象とする -- RESTish - - 原理的な 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 は広く受け入れられており、コレに対応する様々なツールやフレームワークといったエコシステムがあり、中には定義された設定がうまく認識されない場合がある。本規約では対応していないツールが多い場合、特定の記法を非推奨とすることがあり、同時にその理由も説明する - - 全ての言語・フレームワーク・ツールの対応状況は調査しきれていないため、利用するプロダクトの対応状況は利用者側で確認をお願いする +[Web API設計の前提条件](prerequisite.md)を参照ください。 # Web API 自体の設計について diff --git a/documents/forOpenAPISpecification/prerequisite.md b/documents/forOpenAPISpecification/prerequisite.md new file mode 100644 index 00000000..9abc9e35 --- /dev/null +++ b/documents/forOpenAPISpecification/prerequisite.md @@ -0,0 +1,20 @@ +# 前提条件 + +本規約は以下の前提で作成されたものである。 + +- 業務システム向けの 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 は広く受け入れられており、コレに対応する様々なツールやフレームワークといったエコシステムがあり、中には定義された設定がうまく認識されない場合がある。本規約では対応していないツールが多い場合、特定の記法を非推奨とすることがあり、同時にその理由も説明する + - 全ての言語・フレームワーク・ツールの対応状況は調査しきれていないため、利用するプロダクトの対応状況は利用者側で確認をお願いする From e08aaad1be9eaac0243bd869d4e66699ac00f94c Mon Sep 17 00:00:00 2001 From: future-mano Date: Fri, 10 Nov 2023 15:25:30 +0900 Subject: [PATCH 2/2] =?UTF-8?q?=E3=83=95=E3=82=A1=E3=82=A4=E3=83=AB?= =?UTF-8?q?=E3=83=95=E3=82=A9=E3=83=BC=E3=83=9E=E3=83=83=E3=83=88=E3=82=92?= =?UTF-8?q?=E5=88=87=E3=82=8A=E5=87=BA=E3=81=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../OpenAPI_Specification_2.0.md | 65 ++-------------- .../forOpenAPISpecification/file_standards.md | 76 +++++++++++++++++++ 2 files changed, 81 insertions(+), 60 deletions(-) create mode 100644 documents/forOpenAPISpecification/file_standards.md diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md index 1be39cb8..c0d76eee 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md @@ -17,72 +17,17 @@ meta: [OpenAPI Specification 2.0（Swagger, OAS2）](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md)定義についてのコーディング規約をまとめます。より新しいバージョンとして OAS 3.0.3 規約（作成中）がありますので、ご注意ください。 -## 前提条件 +## 適用箇所 -[Web API設計の前提条件](prerequisite.md)を参照ください。 +本規約は以下の[前提条件](prerequisite.md)で作られたものである。 -# Web API 自体の設計について +## Web API 自体の設計について [API 設計標準](API_Design.md) に準じる。 -# 全体規約 +## ファイルフォーマット -ファイル全体に関わることとや、YAML 記法についての方針をまとめる。 - -- YAML、JSON のいずれかのフォーマットで記載できるが、 **YAML で記載** すること - - YAML は視覚的に見やすいとされ、レビューや差分管理が比較的行いやすいと考えられるため -- ファイルの拡張子は `yaml` とする。通常ファイル名は `swagger.yaml` を推奨する - - もし、複数の Swagger 定義を管理するため区別したい場合は `${service}_swagger.yaml` とする - - `${service}` にはサービス名を指定する -- [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`） - -- 複数項目を指定する場合は、 **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 -``` +[ファイルフォーマット規約](yaml_standards.md)に準じる。 # 要素規約 diff --git a/documents/forOpenAPISpecification/file_standards.md b/documents/forOpenAPISpecification/file_standards.md new file mode 100644 index 00000000..607b6006 --- /dev/null +++ b/documents/forOpenAPISpecification/file_standards.md @@ -0,0 +1,76 @@ +# ファイルフォーマット規約 + +## フォーマット + +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 +```