From bf536b6911761f0d6320223e4e9e060fb7469bf4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fujita=20Haruka=28=E8=97=A4=E7=94=B0=20=E6=98=A5=E4=BD=B3?= =?UTF-8?q?=29?= Date: Sat, 18 Nov 2023 18:52:04 +0900 Subject: [PATCH 1/2] feat: add file-component section --- .../OpenAPI_Specification_3.0.3.md | 769 ++++++++++++++---- .../reference/divided_files_sample.zip | Bin 0 -> 7267 bytes 2 files changed, 617 insertions(+), 152 deletions(-) create mode 100644 documents/forOpenAPISpecification/reference/divided_files_sample.zip diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index f9cd6b1b..99021d16 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -481,7 +481,7 @@ tags: ## 値が存在しないという状態の表現 -#### undefined と null +### undefined と null - リクエスト/レスポンスにおいて、ある項目の値が存在しないという状態を表現する場合、① その項目自体を含めず `undefined` とする方法と、② 値に `null` を使用する方法がある。 @@ -539,7 +539,7 @@ tags: - 原則としては、①`undefined` による定義を使用する方が、API 仕様の表現が煩雑にならず、また通信サイズの点からも有利である。 -#### 差分更新 API の場合 +### 差分更新 API の場合 - 差分更新（PATCH）API においては、項目が更新対象外であることと、項目が更新してクリアする対象であることを明確に区別する必要がある。このような場合には、以下のいずれかの方法を採用する。 @@ -555,7 +555,7 @@ tags: - この場合、OpenAPI からの自動生成モデルにはカスタマイズが必要となる。 - カスタムモデルの例 (参照元: [技術ブログ](https://future-architect.github.io/articles/20211028b/#プログラムの観点)) -#### 各言語による表現の違い +### 各言語による表現の違い
Golang @@ -597,144 +597,143 @@ tags: // Deserialize decoder.Decode(&v) fmt.Printf("After decoded: %#v\n", v) + ``` -```` + - シリアライズ後のjsonを見ると、値がセットされない場合には、項目にゼロ値（ポインタ型は`nil`, string型は空文字、int型は`0`）が入っている。 + - 項目がゼロ値の場合に`omitempty` が付与されていると、 項目ごと除外されている（`undefined` となっている）。 + + ```json + { + "not_nullable_string_1": "value", + "not_nullable_string_2": "", + "nullable_string_1": null, + "nullable_string_3": null, + "not_nullable_int_1": 1, + "not_nullable_int_2": 0, + "nullable_int_1": null, + "nullable_int_3": null + } + ``` -- シリアライズ後のjsonを見ると、値がセットされない場合には、項目にゼロ値（ポインタ型は`nil`, string型は空文字、int型は`0`）が入っている。 -- 項目がゼロ値の場合に`omitempty` が付与されていると、 項目ごと除外されている（`undefined` となっている）。 + - デシリアライズ後の構造体を見ると、json の項目が`undefined`であっても `null` であっても、`nil` として保持されている。 -```json - { - "not_nullable_string_1": "value", - "not_nullable_string_2": "", - "nullable_string_1": null, - "nullable_string_3": null, - "not_nullable_int_1": 1, - "not_nullable_int_2": 0, - "nullable_int_1": null, - "nullable_int_3": null - } -```` - -- デシリアライズ後の構造体を見ると、json の項目が`undefined`であっても `null` であっても、`nil` として保持されている。 - -```go - After decoded: - Data{ - NotNullableString1:"value", - NotNullableString2:"", - NullableString1:(*string)(nil), - NullableString2:(*string)(nil), - NullableString3:(*string)(nil), - NullableString4:(*string)(nil), - NotNullableInt1:1, - NotNullableInt2:0, - NullableInt1:(*int64)(nil), - NullableInt2:(*int64)(nil), - NullableInt3:(*int64)(nil), - NullableInt4:(*int64)(nil) - } -``` + ```go + After decoded: + Data{ + NotNullableString1:"value", + NotNullableString2:"", + NullableString1:(*string)(nil), + NullableString2:(*string)(nil), + NullableString3:(*string)(nil), + NullableString4:(*string)(nil), + NotNullableInt1:1, + NotNullableInt2:0, + NullableInt1:(*int64)(nil), + NullableInt2:(*int64)(nil), + NullableInt3:(*int64)(nil), + NullableInt4:(*int64)(nil) + } + ```
Java -- Java の場合、`int` や `double` などのプリミティブ型は `null` になれないため、`nullable` にするためには、それぞれのラッパークラスである参照型（`Integer`, `Double` など）を使用する必要がある。 -- json にシリアライズ後に`null` の項目を保持するか否かは、例えば、[Jackson ライブラリ](https://github.com/FasterXML)を用いて以下のように区別される。 - -```java - public class Data { - public Data(){}; - public Data(String str1, String str2, int notNullableInt){ - this.nullableString1 = str1; - this.nullableString2 = str2; - this.notNullableInt = notNullableInt; - }; - @JsonInclude(JsonInclude.Include.ALWAYS) - private String nullableString1; - - @JsonInclude(JsonInclude.Include.NON_NULL) - private String nullableString2; - - private int notNullableInt; - - // Setters - public void setNullableString1(String nullableString1) { - this.nullableString1 = nullableString1; - } - public void setNullableString2(String nullableString2) { - this.nullableString2 = nullableString2; - } - public void setNotNullableInt(int notNullableInt) { - this.notNullableInt = notNullableInt; - } - // Getters - public String getNullableString1() { - return nullableString1; - } - public String getNullableString2() { - return nullableString2; - } - public int getNotNullableInt() { - return notNullableInt; - } - } -``` + - Java の場合、`int` や `double` などのプリミティブ型は `null` になれないため、`nullable` にするためには、それぞれのラッパークラスである参照型（`Integer`, `Double` など）を使用する必要がある。 + - json にシリアライズ後に`null` の項目を保持するか否かは、例えば、[Jackson ライブラリ](https://github.com/FasterXML)を用いて以下のように区別される。 + + ```java + public class Data { + public Data(){}; + public Data(String str1, String str2, int notNullableInt){ + this.nullableString1 = str1; + this.nullableString2 = str2; + this.notNullableInt = notNullableInt; + }; + @JsonInclude(JsonInclude.Include.ALWAYS) + private String nullableString1; + + @JsonInclude(JsonInclude.Include.NON_NULL) + private String nullableString2; + + private int notNullableInt; + + // Setters + public void setNullableString1(String nullableString1) { + this.nullableString1 = nullableString1; + } + public void setNullableString2(String nullableString2) { + this.nullableString2 = nullableString2; + } + public void setNotNullableInt(int notNullableInt) { + this.notNullableInt = notNullableInt; + } + // Getters + public String getNullableString1() { + return nullableString1; + } + public String getNullableString2() { + return nullableString2; + } + public int getNotNullableInt() { + return notNullableInt; + } + } + ``` -```java - // Set nothing to the fields. - Data dataWithNothing = new Data(); - // Set intial values to the fields. - Data dataWithInitialValues = new Data(null,null,0); - // Set values to the fields. - Data dataWithValues = new Data("","",1); - - List dataList = Arrays.asList(dataWithNothing, dataWithInitialValues, dataWithValues); - ObjectMapper mapper = new ObjectMapper(); - for(Data d : dataList){ - // Serialize - String json = mapper.writeValueAsString(d); - System.out.println(json); - - // Deserialize - Data deserialized = mapper.readValue(json, Data.class); - System.out.println(ToStringBuilder.reflectionToString(deserialized, ToStringStyle.SHORT_PREFIX_STYLE)); - } -``` + ```java + // Set nothing to the fields. + Data dataWithNothing = new Data(); + // Set intial values to the fields. + Data dataWithInitialValues = new Data(null,null,0); + // Set values to the fields. + Data dataWithValues = new Data("","",1); + + List dataList = Arrays.asList(dataWithNothing, dataWithInitialValues, dataWithValues); + ObjectMapper mapper = new ObjectMapper(); + for(Data d : dataList){ + // Serialize + String json = mapper.writeValueAsString(d); + System.out.println(json); + + // Deserialize + Data deserialized = mapper.readValue(json, Data.class); + System.out.println(ToStringBuilder.reflectionToString(deserialized, ToStringStyle.SHORT_PREFIX_STYLE)); + } + ``` -- シリアライズ後の json を見ると、参照型`String`の初期値は`null`、プリミティブ型`int`の初期値は`0`となっている。 -- `@JsonInclude(JsonInclude.Include.ALWAYS)` アノテーションを付与した項目は、値が`null`の場合でも項目が保持される。 -- `@JsonInclude(JsonInclude.Include.NON_NULL)` アノテーションを付与した項目は、値が`null`の場合には項目ごと除外されている（`undefined`となっている）。 + - シリアライズ後の json を見ると、参照型`String`の初期値は`null`、プリミティブ型`int`の初期値は`0`となっている。 + - `@JsonInclude(JsonInclude.Include.ALWAYS)` アノテーションを付与した項目は、値が`null`の場合でも項目が保持される。 + - `@JsonInclude(JsonInclude.Include.NON_NULL)` アノテーションを付与した項目は、値が`null`の場合には項目ごと除外されている（`undefined`となっている）。 -```json - { - "nullableString1": null, - "notNullableInt": 0 - } + ```json + { + "nullableString1": null, + "notNullableInt": 0 + } - { - "nullableString1": null, - "notNullableInt": 0 - } + { + "nullableString1": null, + "notNullableInt": 0 + } - { - "nullableString1": "", - "nullableString2": "", - "notNullableInt": 1 - } -``` + { + "nullableString1": "", + "nullableString2": "", + "notNullableInt": 1 + } + ``` -- デシリアライズ後のオブジェクトを見ると、json の項目が`undefined`であっても `null` であっても、`null` として保持されている。 + - デシリアライズ後のオブジェクトを見ると、json の項目が`undefined`であっても `null` であっても、`null` として保持されている。 -```java - Data[nullableString1=,nullableString2=,notNullableInt=0] + ```java + Data[nullableString1=,nullableString2=,notNullableInt=0] - Data[nullableString1=,nullableString2=,notNullableInt=0] + Data[nullableString1=,nullableString2=,notNullableInt=0] - Data[nullableString1=,nullableString2=,notNullableInt=1] -``` + Data[nullableString1=,nullableString2=,notNullableInt=1] + ```
@@ -774,49 +773,515 @@ tags: console.log(deserialized) ``` -- シリアライズ後のjsonを見ると、`undefined`定義した項目は除外されている。 - -```json -{ - "nullable_string1": "value1", - "nullable_string2": "", - "nullable_string3": null, - "nullable_num1": 1, - "nullable_num2": 0, - "nullable_num3": null -} -``` + - シリアライズ後のjsonを見ると、`undefined`定義した項目は除外されている。 -- デシリアライズ後のオブジェクトを見ると、json の項目が`null` の場合にのみ`null` として保持されており、項目のない場合と区別されている。 + ```json + { + "nullable_string1": "value1", + "nullable_string2": "", + "nullable_string3": null, + "nullable_num1": 1, + "nullable_num2": 0, + "nullable_num3": null + } + ``` -```typescript -nullable_string1: "value1"; -nullable_string2: ""; -nullable_string3: null; -nullable_num1: 1; -nullable_num2: 0; -nullable_num3: null; -``` + - デシリアライズ後のオブジェクトを見ると、json の項目が`null` の場合にのみ`null` として保持されており、項目のない場合と区別されている。 + ```typescript + nullable_string1: "value1"; + nullable_string2: ""; + nullable_string3: null; + nullable_num1: 1; + nullable_num2: 0; + nullable_num3: null; + ``` +### 参照リンク + +- `undefined` と `null` の使い方について詳細な解説は、[技術ブログ記事](https://future-architect.github.io/articles/20211028b/)を参照されたい。 +- OpenAPI 定義を DB 定義に対応させることにより、異なる API 間で整合のとれた処理設計をすることがのぞましい。DB 定義と OpenAPI 定義の対応例は、[DB 定義と OpenAPI 定義のマッピング](./reference/DB_OpenAPI_Mapping_Example.md)を参照されたい。 + ## ファイル単位 OpenAPI ドキュメントは単一のファイルで構成することも複数の分割されたファイルで構成することもできるが、**複数のファイルに分割する**ことを推奨する。 理由は下記の通りである。 -- XXX -- XXX +- **APIごとに担当者を分けて設計する場合などに、複数人による編集によって意図しないコンフリクトが発生することを防ぐ。** +- **ファイルの肥大化による、可読性の低下を防ぐ。** + +### 分割方法の選定 + +開発方針やOpenAPIの使用用途に合わせて、都合の良いファイルの分割方法を採用する。例えば、以下のような方法がある。 + +1. APIごとに設計担当者を分けて、それぞれにOpenAPIを編集する場合は、APIの単位で分割する。 +2. テストツールとして [stoplightio/prism](https://github.com/stoplightio/prism)を使用する場合、テストケースごとにデータファイルを作成して、`examples` にファイルパスを指定する。 + +### サンプル説明 + +分割方法1, 2の両方に当てはまる場合のサンプルを用いて説明する。`openapi.yaml` とディレクトリ構成は下の通り。サンプルの全量は [サンプルzip Download](./reference/divided_files_sample.zip)からダウンロード可能。 + +- 機能単位（path, method単位）にディレクトリを作成して、それぞれの定義ファイルを格納する。ディレクトリ名は `{path}_{method}` とすると管理し易い。 +- `components` の `schemas` には、 + - 各APIごとのリクエスト/リスポンスモデルを切り出して記載する（例えば、`ResPetsPetIdGet`）。 + - API間で同じモデルを使用する場合は共通化して記載する（例えば、`Pet`）。 + - 各APIのリクエスト/リスポンスモデルの中で、モデルがネストする場合は、各モデルの単位で書き出す（例えば、`PetDetail`, `Pedigree`）。 + +
+ ファイル分割例： openapi.yaml + + ```yaml + openapi: "3.0.3" + info: + version: 1.0.0 + title: Swagger Petstore + license: + name: MIT + servers: + - url: http://petstore.swagger.io/v1 + paths: + /pets: + get: + $ref: "./pets_get/pets_get.yaml" + post: + $ref: "./pets_post/pets_post.yaml" + /pets/{petId}: + get: + $ref: "./pets-pet-id_get/pets-pet-id_get.yaml" + + components: + schemas: + ResPetsGet: + $ref: "./pets_get/response.yaml" + ReqPetsPost: + $ref: "./pets_post/request.yaml" + ResPetsPetIdGet: + $ref: "./pets-pet-id_get/response.yaml#/ResPetsPetIdGet" + PetDetail: + $ref: "./pets-pet-id_get/response.yaml#/PetDetail" + Pedigree: + $ref: "./pets-pet-id_get/response.yaml#/Pedigree" + Pet: + $ref: "./common/pet.yaml" + Error: + $ref: "./common/error.yaml" + ``` -（相談事項） +
-- 分割のパターンがあるのであれば、いくつかケースに応じてパターン分けして記載する。 -- ファイルの命名についてもここで触れる +
+ ファイル分割例： ディレクトリ構成 + + ```sh + │ openapi.gen.yaml + │ openapi.yaml + │ + ├─common + │ error.yaml + │ pet.yaml + │ + ├─pets-pet-id_get + │ │ pets-pet-id_get.yaml + │ │ response.yaml + │ │ + │ └─examples + │ res_example1.yaml + │ + ├─pets_get + │ │ pets_get.yaml + │ │ response.yaml + │ │ + │ └─examples + │ res_example1.yaml + │ res_example2.yaml + │ + └─pets_post + │ pets_post.yaml + │ request.yaml + │ + └─examples + req_example1.yaml + ``` -#### 参照リンク +
+ +- `openapi.yaml` の `paths` に記載したAPIファイルは以下のように作成する。`schema` にて `openapi.yaml` に指定したキー（`../openapi.yaml#/components/schemas/ResPetsPetIdGet`）を参照する。 +- `examples` には、各APIのテストケースIDをキーとして指定（`ResExample1`）し、`value` に該当するテストケースのデータファイルパスを指定（`./examples/res_example1.yaml`）する。ファイル名は、指定したキーをスネークケースに変換したものを使用するとよい。 + +
+ API別ファイルの記載例： pets-pet-id_get.yaml + + ```yaml + summary: Details for a pet + operationId: get-pets-pet-id + tags: + - pets + parameters: + - name: petId + in: path + required: true + description: The id of the pet to retrieve + schema: + type: string + responses: + "200": + description: Expected response to a valid request + content: + application/json: + schema: + $ref: "../openapi.yaml#/components/schemas/ResPetsPetIdGet" + examples: + ResExample1: + value: + $ref: "./examples/res_example1.yaml" + "404": + description: not found error + content: + application/json: + schema: + $ref: "../openapi.yaml#/components/schemas/Error" + "500": + description: unexpected error + content: + application/json: + schema: + $ref: "../openapi.yaml#/components/schemas/Error" + ``` + +
+ +- `schema` ファイルの例は以下の通り。 + - 複数API間に共通のモデルは `openapi.yaml` に指定したキーを指定する（`../openapi.yaml#/components/schemas/Pet`）。 + - ネストしているモデルは `openapi.yaml` に指定したキーを経由して参照できるようにする（`../openapi.yaml#/components/schemas/PetDetail`, `../openapi.yaml#/components/schemas/Pedigree`）。 + +
+ schemaファイル記載例： pets-pet-id_get/response.yaml + + ```yaml + ResPetsPetIdGet: + required: + - pet + - pet_detail + type: object + properties: + pet: + $ref: "../openapi.yaml#/components/schemas/Pet" + pet_detail: + $ref: "../openapi.yaml#/components/schemas/PetDetail" + + PetDetail: + type: object + properties: + breeder: + type: string + date_of_birth: + type: string + format: date + pedigree: + $ref: "../openapi.yaml#/components/schemas/Pedigree" + + Pedigree: + required: + - registration_no + - date_of_registration + - pedigree_image + type: object + properties: + registration_no: + type: integer + format: int64 + date_of_registration: + type: string + format: date + pedigree_image: + type: string + ``` + +
+ +- OpenAPIの使用用途により、分割ファイルを1つのファイルにまとめる必要がある場合には、例えば[swagger-cli](https://apitools.dev/swagger-cli/)を使用して以下コマンドを実行する。 + + ```bash + swagger-cli bundle openapi.yaml --outfile openapi.gen.yaml --type yaml + ``` + +
+ ファイルBundle後： openapi.gen.yaml + + ```yaml + openapi: 3.0.3 + info: + version: 1.0.0 + title: Swagger Petstore + license: + name: MIT + servers: + - url: 'http://petstore.swagger.io/v1' + paths: + /pets: + get: + summary: List all pets + operationId: get-pets + tags: + - pets + parameters: + - name: limit + in: query + description: How many items to return at one time (max 100) + required: false + schema: + type: integer + maximum: 100 + format: int32 + responses: + '200': + description: A paged array of pets + headers: + x-next: + description: A link to the next page of responses + schema: + type: string + content: + application/json: + schema: + $ref: '#/components/schemas/ResPetsGet' + examples: + ResExample1: + value: + - id: 10001 + name: ToyPoodle + category: dog + sub_category: ToyPoodle + age: 1 + sex: male + note: friendly + tag: dog10001 + - id: 10002 + name: Chihuahua + category: dog + sub_category: Chihuahua + age: 1 + sex: female + note: friendly + tag: dog10002 + - id: 10003 + name: Shiba + category: dog + sub_category: Shiba + age: 1 + sex: male + note: friendly + tag: dog10003 + - id: 10004 + name: MiniatureDachshund + category: dog + sub_category: MiniatureDachshund + age: 1 + sex: female + note: friendly + tag: dog10004 + ResExample2: + value: [] + '404': + description: not found error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + post: + summary: Register a pet + operationId: post-pets + tags: + - pets + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ReqPetsPost' + examples: + ReqExample1: + value: + pet: + id: 10005 + name: FrenchBulldog + category: dog + sub_category: FrenchBulldog + age: 1 + sex: male + note: friendly + tag: dog10005 + required: false + responses: + '201': + description: Null response + '404': + description: not found error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/pets/{petId}': + get: + summary: Details for a pet + operationId: get-pets-pet-id + tags: + - pets + parameters: + - name: petId + in: path + required: true + description: The id of the pet to retrieve + schema: + type: string + responses: + '200': + description: Expected response to a valid request + content: + application/json: + schema: + $ref: '#/components/schemas/ResPetsPetIdGet' + examples: + ResExample1: + value: + pet: + id: 10001 + name: ToyPoodle + category: dog + sub_category: ToyPoodle + age: 1 + sex: male + note: friendly + tag: dog10001 + pet_detail: + breeder: BreederName + date_of_birth: '2023-10-31' + pedigree: + registration_no: 11111111 + date_of_registration: '2023-10-31' + pedigree_image: 9j2wBDAA...8QAPxAAAQQABAMGBAYDAAEDAg + '404': + description: not found error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '500': + description: unexpected error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + components: + schemas: + ResPetsGet: + type: array + maxItems: 100 + items: + $ref: '#/components/schemas/Pet' + ReqPetsPost: + required: + - pet + type: object + properties: + pet: + $ref: '#/components/schemas/Pet' + ResPetsPetIdGet: + required: + - pet + - pet_detail + type: object + properties: + pet: + $ref: '#/components/schemas/Pet' + pet_detail: + $ref: '#/components/schemas/PetDetail' + PetDetail: + type: object + properties: + breeder: + type: string + date_of_birth: + type: string + format: date + pedigree: + $ref: '#/components/schemas/Pedigree' + Pedigree: + required: + - registration_no + - date_of_registration + - pedigree_image + type: object + properties: + registration_no: + type: integer + format: int64 + date_of_registration: + type: string + format: date + pedigree_image: + type: string + Pet: + type: object + required: + - id + - name + - category + - age + - sex + properties: + id: + type: integer + format: int64 + name: + type: string + maxLength: 50 + category: + type: string + maxLength: 10 + sub_category: + type: string + maxLength: 50 + age: + type: integer + format: int32 + sex: + type: string + maxLength: 6 + note: + type: string + maxLength: 200 + tag: + type: string + maxLength: 20 + Error: + type: object + required: + - code + - message + properties: + code: + type: integer + format: int32 + message: + type: string + + ``` + +
-- `undefined` と `null` の使い方について詳細な解説は、[技術ブログ記事](https://future-architect.github.io/articles/20211028b/)を参照されたい。 -- OpenAPI 定義を DB 定義に対応させることにより、異なる API 間で整合のとれた処理設計をすることがのぞましい。DB 定義と OpenAPI 定義の対応例は、[DB 定義と OpenAPI 定義のマッピング](./reference/DB_OpenAPI_Mapping_Example.md)を参照されたい。 # 各種ツール、サービスとの統合 diff --git a/documents/forOpenAPISpecification/reference/divided_files_sample.zip b/documents/forOpenAPISpecification/reference/divided_files_sample.zip new file mode 100644 index 0000000000000000000000000000000000000000..6ffeea93ed2a3e5b245ee962a2c7374719c9725c GIT binary patch literal 7267 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 literal 0 HcmV?d00001 From cc44a7a8eea8ffc3ec5c41ba4885c96d1f938a50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fujita=20Haruka=28=E8=97=A4=E7=94=B0=20=E6=98=A5=E4=BD=B3?= =?UTF-8?q?=29?= Date: Sat, 18 Nov 2023 20:36:04 +0900 Subject: [PATCH 2/2] fix: import DB_OpenAPI_Mapping_Example.md from GitLab --- .../reference/DB_OpenAPI_Mapping_Example.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 documents/forOpenAPISpecification/reference/DB_OpenAPI_Mapping_Example.md diff --git a/documents/forOpenAPISpecification/reference/DB_OpenAPI_Mapping_Example.md b/documents/forOpenAPISpecification/reference/DB_OpenAPI_Mapping_Example.md new file mode 100644 index 00000000..52dfdd31 --- /dev/null +++ b/documents/forOpenAPISpecification/reference/DB_OpenAPI_Mapping_Example.md @@ -0,0 +1,18 @@ +# DB OpenAPI Mapping Example + +|データの種類|DB型|DDL定義|OpenAPI
項目必須/非必須|OpenAPI
Type/その他定義|API
リクエスト/リスポンス|備考| +|:----|:----|:----|:----|:----|:----|:----| +|区分値|varchar|NOT NULL, カラム名 <> ''|required|string/enum|項目必須、空値は許容しない| | +| | |NOT NULL default ''|-|string/enum|項目非必須、空値はundefinedまたは空文字として定義|空値を空文字で定義する場合、enumに空文字を含む必要がある。| +|フラグ|varchar|NOT NULL, カラム名 <> ''|required|string/enum|項目必須、空値は許容しない| | +| | |NOT NULL default ''|-|string/enum|項目非必須、空値はundefinedまたは空文字として定義|空値を空文字で定義する場合、enumに空文字を含む必要がある。| +|数値|integer|NOT NULL|required|integer|項目必須、空値は許容しない| | +| | |-|nullable: true|integer|項目非必須、空値はundefinedまたはnullとして定義| | +|数値（精度有）|numeric|NOT NULL|required|string/正規表現pattern|項目必須、空値は許容しない| | +| | |-|nullable: true|string/正規表現pattern|項目非必須、空値はundefinedまたはnullとして定義| | +|日付/時刻|date / timestamp|NOT NULL|required|string/format指定または正規表現pattern|項目必須、空値は許容しない| | +| | |-|nullable: true|string/format指定または正規表現pattern|項目非必須、空値はundefinedまたはnullとして定義| | +|コード/番号|varchar|NOT NULL, カラム名 <> ''|required|string/正規表現patternや桁数指定|項目必須、空値は許容しない| | +| | |NOT NULL default ''|-|string/正規表現patternや桁数指定|項目非必須、空値はundefinedまたは空文字として定義| | +|名前 / メモ|varchar / text|NOT NULL, カラム名 <> ''|required|string/正規表現patternや桁数指定|項目必須、空値は許容しない| | +| | |NOT NULL default ''|-|string/正規表現patternや桁数指定|項目非必須、空値はundefinedまたは空文字として定義| |