From 08f30b5709787486c4a980f6c47b9ca77d84afe0 Mon Sep 17 00:00:00 2001 From: Junki Mano Date: Fri, 10 Nov 2023 15:39:42 +0900 Subject: [PATCH] Feature/openapispec (#62) 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 +```