From b4dd231431db7be4291660086c0b0dfff534c31f Mon Sep 17 00:00:00 2001 From: future-mano Date: Fri, 10 Nov 2023 14:58:29 +0900 Subject: [PATCH] =?UTF-8?q?=E5=89=8D=E6=8F=90=E6=9D=A1=E4=BB=B6=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 | 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 は広く受け入れられており、コレに対応する様々なツールやフレームワークといったエコシステムがあり、中には定義された設定がうまく認識されない場合がある。本規約では対応していないツールが多い場合、特定の記法を非推奨とすることがあり、同時にその理由も説明する + - 全ての言語・フレームワーク・ツールの対応状況は調査しきれていないため、利用するプロダクトの対応状況は利用者側で確認をお願いする