OpenAPI規約を1つに統合 (#207)

Author: ma91n

documents/forOpenAPISpecification/API_Design.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
+```
 
 # 要素規約