前提条件を切り出し (#61)

Author: ma91n

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 自体の設計について
 

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 は広く受け入れられており、コレに対応する様々なツールやフレームワークといったエコシステムがあり、中には定義された設定がうまく認識されない場合がある。本規約では対応していないツールが多い場合、特定の記法を非推奨とすることがあり、同時にその理由も説明する
+  - 全ての言語・フレームワーク・ツールの対応状況は調査しきれていないため、利用するプロダクトの対応状況は利用者側で確認をお願いする