From d62a1d01af41d9aeda32c9f7c7ddba21605b095f Mon Sep 17 00:00:00 2001 From: ma91n Date: Fri, 22 Dec 2023 14:55:07 +0900 Subject: [PATCH 1/4] Add validation at OpenAPISpec --- .../OpenAPI_Specification_2.0.md | 176 ++++++++++-------- .../OpenAPI_Specification_3.0.3.md | 110 ++++++++++- 2 files changed, 205 insertions(+), 81 deletions(-) diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md index 0740a0bc..918e9134 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md @@ -680,97 +680,113 @@ definitions: ## バリデーションについて +OpenAPI 定義を記載するにあたり、バリデーションをどこまで厳密に定義すべきかという議論はよく行いがちである。 + リクエストパラメータの各項目に対して、必須・型・桁・区分値・日付・正規表現のチェックが行える。レスポンスで用いるモデルについても同様に設定でき、`enum`, `pattern` 以外は API の利用者（クライアント）側の DB 設計などに必要な型桁情報を渡すのに有用であるため、できる限り詳しく指定する。 -- 必須（`required`） - - 必須パラメータのみ `required: true` を定義する -- デフォルト値（`default`） +### 必須 - - パラメータにデフォルト値がある場合は定義する +必須パラメータのみ `required: true` を定義する - ```yaml - # ex. enum - name: limit - type: number - format: integer - minimum: 1 - maximum: 100 - default: 20 - description: 検索結果の項目数上限（1~100が指定可能） - ``` +### デフォルト値 - - API 公開後に、default 値を変更してはならない（API の互換性が崩れるため）。もし変更する場合は、API のバージョンを上げること - -- 型（`type`） - - `string(文字列)`, `number（数値）`, `integer（整数値）`, `boolean（真偽値）` `array（配列）`, `file（ファイル）` のうちどれか指定する -- フォーマット（`format`） は以下の型の詳細情報を示すもので、可能な限り設定する - - `integer` （整数） - - `int32`, `int64` - - `number` （数値） - - `float`, `double` - - `string` （バイナリ） - - `byte`: Base64 でエンコードされた文字列 - - `binary`: バイト配列 - - `string` （日付） - - `date`: [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) full-date - - 項目名は `_on` を接尾辞につけることを推奨とする - - `date-time`: [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) date-time - - 項目名は `_at` を接尾辞につけることを推奨とする - - `string` （その他） - - `password`: Swagger UI で入力が隠される - - その他、 `email`, `uuid` など Open API 仕様に存在しない任意のフォーマットを独自のドキュメント生成などのために記載しても良い -- 桁 - - 文字列 - - 最大桁数：`maxLength` - - 最小桁数：`minLength` - - 数値または整数値 - - 最小値（境界値を含む）：`minimum` - - 最大値（境界値を含む）：`maximum` - - 境界値を含まない場合のみ`exclusiveMinimum: true`または`exclusiveMaximum: true`を定義する。minimum, maximum で代用できる場合は利用しない - - 配列: - - 最大要素数：`maxItems` - - 最小要素数：`minItems` - - `required: true`の場合は原則として`minItems: 1`を定義する - - `uniqueItems` は必須で指定する（通常は一意であるべき） - - API 公開後に、レスポンスの `maxLength` を以前より大きい値に変更してはならい - - レスポンスの `maxLength` など API 利用者側システムの DB の ERD 定義のインプットになる事が多いため。もし行う場合は API のバージョンを上げることや、連携先に桁数変更の旨を調整するなどの考慮を行う -- 区分値（`enum`） - - - `description`に区分値の論理名を記載する +パラメータにデフォルト値がある場合は`default` を定義する。 - ```yaml - name: gender - type: string - enum: ["0", "1", "2", "9"] - description: | - 性別 - 0: 不明 - 1: 男 - 2: 女 - 9: 適用不能 - ``` +```yaml +# ex. enum +name: limit +type: number +format: integer +minimum: 1 +maximum: 100 +default: 20 +description: 検索結果の項目数上限（1~100が指定可能） +``` + +【注意】API 公開後に、default 値を変更してはならない（API の互換性が崩れるため）。もし変更する場合は、API のバージョンを上げること。 + + +### 型・フォーマット + +型（`type`）は `string(文字列)`, `number（数値）`, `integer（整数値）`, `boolean（真偽値）` `array（配列）`, `file（ファイル）` のうちどれか指定する. + +フォーマット（`format`） は以下の型の詳細情報を示すもので、可能な限り設定する。 + +- `integer` （整数） + - `int32`, `int64` +- `number` （数値） + - `float`, `double` +- `string` （バイナリ） + - `byte`: Base64 でエンコードされた文字列 + - `binary`: バイト配列 +- `string` （日付） + - `date`: [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) full-date(例: 2023-07-21) + - 項目名は `_on` を接尾辞につけることを推奨とする + - `date-time`: [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) date-time(例: 2023-07-21T17:32:28Z) + - 項目名は `_at` を接尾辞につけることを推奨とする +- `string` （その他） + - `password`: Swagger UI で入力が隠される + - その他、 `email`, `uuid` など Open API 仕様に存在しない任意のフォーマットを独自のドキュメント生成などのために記載しても良い + +### 桁 - - **固定値** の場合も enum を 1 つだけ指定して表現する。この場合もレスポンスで利用する場合は指定しない +データ型によって、利用できる桁を指定する項目が異なる。可能な限り設定する。 - ```yaml - name: file_layout - type: string - enum: ["json"] - description: ファイルレイアウト - ``` +- 文字列 + - 最大桁数：`maxLength` + - 最小桁数：`minLength` +- 数値または整数値 + - 最小値（境界値を含む）：`minimum` + - 最大値（境界値を含む）：`maximum` + - 境界値を含まない場合のみ`exclusiveMinimum: true`または`exclusiveMaximum: true`を定義する。minimum, maximum で代用できる場合は利用しない +- 配列: + - 最大要素数：`maxItems` + - 最小要素数：`minItems` + - `required: true`の場合は原則として`minItems: 1`を定義する + - `uniqueItems` は必須で指定する（通常は一意であるべき） -- その他 +【注意】API 公開後に、レスポンスの `maxLength` を以前より大きい値に変更してはならない。レスポンスの `maxLength` など API 利用者側システムの DB の ERD 定義のインプットになる事が多いため。もし行う場合は API のバージョンを上げることや、連携先に桁数変更の旨を調整するなどの考慮を行う。 - - 正規表現で表現できる文字列は`pattern`を利用して定義する。桁や区分値で代替できる場合は、`pattern` を用いない - - 例: +### 区分値 - ```yaml - remind_time: - type: string - description: リマインド時刻。（hh:mm）形式 - example: 23:59 - pattern: "^(2[0-3]|[01][0-9]):([0-5][0-9])$" - ``` +区分値の場合は `enum` 属性を利用し、`description`には区分値の論理名を記載する。 + +```yaml +name: gender +type: string +enum: ["0", "1", "2", "9"] +description: | + 性別 + 0: 不明 + 1: 男 + 2: 女 + 9: 適用不能 +``` + +### 固定値 + +**固定値** の場合も enum を 1 つだけ指定して表現する。この場合もレスポンスで利用する場合は指定しない + +```yaml +name: file_layout +type: string +enum: ["json"] +description: ファイルレイアウト +``` + +### その他（正規表現） + +正規表現で表現できる文字列は`pattern`を利用して定義する。桁や区分値で代替できる場合は、`pattern` を用いない + +例: + +```yaml +remind_time: + type: string + description: リマインド時刻。（hh:mm）形式 + example: 23:59 + pattern: "^(2[0-3]|[01][0-9]):([0-5][0-9])$" +``` ## ファイルアップロード diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index 2df147b9..fde6d7a3 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -705,7 +705,115 @@ tags: - 要素規約が「どのように書くか」に焦点を当てているのに対し、そもそも「何を書くか」といった部分については、切り出して要素規約から refer させる形の方がスッキリするかも。要素規約に入れられるならそれでよし。描きながらバランス見て。 -## バリデーションをどこまで厳密に定義するか +## バリデーションについて + +OpenAPI 定義を記載するにあたり、バリデーションをどこまで厳密に定義すべきかという議論はよく行いがちである。 + +リクエストパラメータの各項目に対して、必須・型・桁・区分値・日付・正規表現のチェックが行える。レスポンスで用いるモデルについても同様に設定でき、`enum`, `pattern` 以外は API の利用者（クライアント）側の DB 設計などに必要な型桁情報を渡すのに有用であるため、できる限り詳しく指定する。 + +### 必須 + +必須パラメータのみ `required: true` を定義する + +### デフォルト値 + +パラメータにデフォルト値がある場合は`default` を定義する。 + +```yaml +# ex. enum +name: limit +type: number +format: integer +minimum: 1 +maximum: 100 +default: 20 +description: 検索結果の項目数上限（1~100が指定可能） +``` + +【注意】API 公開後に、default 値を変更してはならない（API の互換性が崩れるため）。もし変更する場合は、API のバージョンを上げること。 + + +### 型・フォーマット + +型（`type`）は `string(文字列)`, `number（数値）`, `integer（整数値）`, `boolean（真偽値）` `array（配列）`, `file（ファイル）` のうちどれか指定する. + +フォーマット（`format`） は以下の型の詳細情報を示すもので、可能な限り設定する。 + +- `integer` （整数） + - `int32`, `int64` +- `number` （数値） + - `float`, `double` +- `string` （バイナリ） + - `byte`: Base64 でエンコードされた文字列 + - `binary`: バイト配列 +- `string` （日付） + - `date`: [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) full-date(例: 2023-07-21) + - 項目名は `_on` を接尾辞につけることを推奨とする + - `date-time`: [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) date-time(例: 2023-07-21T17:32:28Z) + - 項目名は `_at` を接尾辞につけることを推奨とする +- `string` （その他） + - `password`: Swagger UI で入力が隠される + - その他、 `email`, `uuid` など Open API 仕様に存在しない任意のフォーマットを独自のドキュメント生成などのために記載しても良い + +### 桁 + +データ型によって、利用できる桁を指定する項目が異なる。可能な限り設定する。 + +- 文字列 + - 最大桁数：`maxLength` + - 最小桁数：`minLength` +- 数値または整数値 + - 最小値（境界値を含む）：`minimum` + - 最大値（境界値を含む）：`maximum` + - 境界値を含まない場合のみ`exclusiveMinimum: true`または`exclusiveMaximum: true`を定義する。minimum, maximum で代用できる場合は利用しない +- 配列: + - 最大要素数：`maxItems` + - 最小要素数：`minItems` + - `required: true`の場合は原則として`minItems: 1`を定義する + - `uniqueItems` は必須で指定する（通常は一意であるべき） + +【注意】API 公開後に、レスポンスの `maxLength` を以前より大きい値に変更してはならない。レスポンスの `maxLength` など API 利用者側システムの DB の ERD 定義のインプットになる事が多いため。もし行う場合は API のバージョンを上げることや、連携先に桁数変更の旨を調整するなどの考慮を行う。 + +### 区分値 + +区分値の場合は `enum` 属性を利用し、`description`には区分値の論理名を記載する。 + +```yaml +name: gender +type: string +enum: ["0", "1", "2", "9"] +description: | + 性別 + 0: 不明 + 1: 男 + 2: 女 + 9: 適用不能 +``` + +### 固定値 + +**固定値** の場合も enum を 1 つだけ指定して表現する。この場合もレスポンスで利用する場合は指定しない + +```yaml +name: file_layout +type: string +enum: ["json"] +description: ファイルレイアウト +``` + +### その他（正規表現） + +正規表現で表現できる文字列は`pattern`を利用して定義する。桁や区分値で代替できる場合は、`pattern` を用いない + +例: + +```yaml +remind_time: + type: string + description: リマインド時刻。（hh:mm）形式 + example: 23:59 + pattern: "^(2[0-3]|[01][0-9]):([0-5][0-9])$" +``` ## 値が存在しないという状態の表現 From a0df51204ce72b0564f58a78a8fe8bedd73f144d Mon Sep 17 00:00:00 2001 From: ma91n Date: Fri, 22 Dec 2023 14:59:10 +0900 Subject: [PATCH 2/4] add components --- .../OpenAPI_Specification_3.0.3.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index fde6d7a3..2ff3124a 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -790,6 +790,25 @@ description: | 9: 適用不能 ``` +OpenAPI 3.0 では区分値の再利用ができるため、横断的に用いる区分値はcomponents側で定義する。 + +```yaml +paths: + /products: + get: + parameters: + - in: query + name: gender + required: true + schema: + $ref: '#/components/schemas/Gender' +components: + schemas: + Gender: + type: string + enum: ["0", "1", "2", "9"] +``` + ### 固定値 **固定値** の場合も enum を 1 つだけ指定して表現する。この場合もレスポンスで利用する場合は指定しない From ccf21fef7156fa9259881bd40067d043c286c17a Mon Sep 17 00:00:00 2001 From: ma91n Date: Fri, 22 Dec 2023 15:02:29 +0900 Subject: [PATCH 3/4] file type --- .../OpenAPI_Specification_3.0.3.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index 2ff3124a..a7a0b358 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -735,7 +735,7 @@ description: 検索結果の項目数上限（1~100が指定可能） ### 型・フォーマット -型（`type`）は `string(文字列)`, `number（数値）`, `integer（整数値）`, `boolean（真偽値）` `array（配列）`, `file（ファイル）` のうちどれか指定する. +型（`type`）は `string(文字列)`, `number（数値）`, `integer（整数値）`, `boolean（真偽値）` `array（配列）` のうちどれか指定する. フォーマット（`format`） は以下の型の詳細情報を示すもので、可能な限り設定する。 @@ -755,6 +755,13 @@ description: 検索結果の項目数上限（1~100が指定可能） - `password`: Swagger UI で入力が隠される - その他、 `email`, `uuid` など Open API 仕様に存在しない任意のフォーマットを独自のドキュメント生成などのために記載しても良い +OpenAPI 3.0では 2.0 に存在した `file` type は存在しない。もし同等の指定をしたい場合は、以下の用に指定する。 + +```yaml +type: string +format: binary # binary file contents +``` + ### 桁 データ型によって、利用できる桁を指定する項目が異なる。可能な限り設定する。 From a5db2690c82f2c674a7d1b1823dfd0c02ca93d81 Mon Sep 17 00:00:00 2001 From: ma91n Date: Fri, 22 Dec 2023 15:03:29 +0900 Subject: [PATCH 4/4] fix typo --- .../forOpenAPISpecification/OpenAPI_Specification_3.0.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index a7a0b358..34dec3cd 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -755,7 +755,7 @@ description: 検索結果の項目数上限（1~100が指定可能） - `password`: Swagger UI で入力が隠される - その他、 `email`, `uuid` など Open API 仕様に存在しない任意のフォーマットを独自のドキュメント生成などのために記載しても良い -OpenAPI 3.0では 2.0 に存在した `file` type は存在しない。もし同等の指定をしたい場合は、以下の用に指定する。 +OpenAPI 3.0では 2.0 に存在した `file` type は存在しない。もし同等の指定をしたい場合は、以下の様に指定する。 ```yaml type: string