From 282cba7cf04da3c2a0b461e07aee0e376f597bcc Mon Sep 17 00:00:00 2001 From: future-fujita Date: Mon, 16 Sep 2024 23:37:22 +0900 Subject: [PATCH 1/3] fix: update divided-file section --- .../OpenAPI_Specification_3.0.3.md | 501 ++++++++++++++++++ .../sample_divided/common/error.yaml | 10 - .../sample_divided/common/pet.yaml | 32 -- .../examples/pets_get/res_example1.yaml | 34 ++ .../examples/pets_get/res_example2.yaml | 2 + .../pets_pet_id_get/res_example1.yaml | 8 + .../examples/pets_post/req_example1.yaml | 10 + .../sample_divided/openapi.gen.yaml | 362 +++++++------ .../sample_divided/openapi.yaml | 54 +- .../examples/res_example1.yaml | 16 - .../pets-pet-id_get/pets-pet-id_get.yaml | 73 --- .../sample_divided/pets/pets.yaml | 167 ++++++ .../sample_divided/pets/pets_pet_id.yaml | 53 ++ .../pets_get/examples/res_example1.yaml | 32 -- .../pets_get/examples/res_example2.yaml | 1 - .../sample_divided/pets_get/pets_get.yaml | 53 -- .../pets_post/examples/req_example1.yaml | 9 - .../sample_divided/pets_post/pets_post.yaml | 40 -- 18 files changed, 1021 insertions(+), 436 deletions(-) delete mode 100644 documents/forOpenAPISpecification/sample_divided/common/error.yaml delete mode 100644 documents/forOpenAPISpecification/sample_divided/common/pet.yaml create mode 100644 documents/forOpenAPISpecification/sample_divided/examples/pets_get/res_example1.yaml create mode 100644 documents/forOpenAPISpecification/sample_divided/examples/pets_get/res_example2.yaml create mode 100644 documents/forOpenAPISpecification/sample_divided/examples/pets_pet_id_get/res_example1.yaml create mode 100644 documents/forOpenAPISpecification/sample_divided/examples/pets_post/req_example1.yaml delete mode 100644 documents/forOpenAPISpecification/sample_divided/pets-pet-id_get/examples/res_example1.yaml delete mode 100644 documents/forOpenAPISpecification/sample_divided/pets-pet-id_get/pets-pet-id_get.yaml create mode 100644 documents/forOpenAPISpecification/sample_divided/pets/pets.yaml create mode 100644 documents/forOpenAPISpecification/sample_divided/pets/pets_pet_id.yaml delete mode 100644 documents/forOpenAPISpecification/sample_divided/pets_get/examples/res_example1.yaml delete mode 100644 documents/forOpenAPISpecification/sample_divided/pets_get/examples/res_example2.yaml delete mode 100644 documents/forOpenAPISpecification/sample_divided/pets_get/pets_get.yaml delete mode 100644 documents/forOpenAPISpecification/sample_divided/pets_post/examples/req_example1.yaml delete mode 100644 documents/forOpenAPISpecification/sample_divided/pets_post/pets_post.yaml diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index 22cf09e8..645a4538 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -1175,6 +1175,507 @@ remind_time: pattern: "^(2[0-3]|[01][0-9]):([0-5][0-9])$" ``` +## ファイル分割 + +OpenAPI ドキュメントは単一のファイルで構成することも複数の分割されたファイルで構成することもできるが、**複数のファイルに分割する**ことを推奨する。 + +理由: + +- API path ごとに担当者を分けて設計する場合などに、複数人による編集によって意図しないコンフリクトが発生することを防ぐ +- ファイルの肥大化による、可読性の低下を防ぐ + +### 分割方法の選定 + +開発方針や OpenAPI の使用用途に合わせて、都合の良いファイルの分割方法を採用する。例えば、以下のような方法がある。 + +1. API path ごとに設計担当者を分けて、それぞれに OpenAPI を編集する場合は、path の単位で分割する。 +2. テストツールとして [stoplightio/prism](https://github.com/stoplightio/prism)を使用する場合、テストケースごとにデータファイルを作成して、`examples` にファイルパスを指定する。 + +### サンプル説明 + +分割方法 1, 2 の両方に当てはまる場合のサンプルを用いて説明する。`openapi.yaml` とディレクトリ構成は下の通り。全量は [sample_divided](https://github.com/future-architect/coding-standards/tree/master/documents/forOpenAPISpecification/sample_divided)を参照すること。 + +- リソース単位にディレクトリを作成して、path ごとに定義ファイルを格納する。 +- `components` の schemas モデルは、大本の openapi.yaml に命名の定義を記載する。モデルの中身は別ファイルとして切り出すことも可能である。 + + ```yaml + # openapi.yaml（ファイル分割例） + openapi: "3.0.3" + info: + version: 1.0.0 + title: Swagger Petstore + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + security: + - Bearer: [] + servers: + - url: http://petstore.swagger.io/v1 + tags: + - name: pets + description: Everything about your Pets + paths: + /pets: + $ref: "./pets/pets.yaml" + /pets/{pet_id}: + $ref: "./pets/pets_pet_id.yaml" + + components: + schemas: + Error: + type: object + properties: + code: + type: integer + format: int32 + message: + type: string + required: + - code + - message + responses: + NotFound: + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + InternalServerError: + description: Internal Server Error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + securitySchemes: + Bearer: + type: http + scheme: bearer + bearerFormat: JWT + description: 'Authenthicaiton with bearer token' + ``` + + ```sh + # ディレクトリ構成（ファイル分割例） + + ├─openapi.gen.yaml + ├─openapi.yaml + │ + ├─examples + │ ├─pets_get + │ │ ├─res_example1.yaml + │ │ └─res_example2.yaml + │ │ + │ ├─pets_pet_id_get + │ │ └─res_example1.yaml + │ │ + │ └─pets_post + │ └─req_example1.yaml + │ + └─pets + ├─pets.yaml + └─pets_pet_id.yaml + ``` + +- `openapi.yaml` の `paths` に記載した API ファイルは以下のように作成する（例: pets-pet-id.yaml）。 +- `examples` には、各 API のテストケース ID をキーとして指定（`ResExample1`）し、該当するテストケースのデータファイルパスを参照させる。ファイル名は、指定したキーをスネークケースに変換したものを使用するとよい。 + +
+ pets-pet-id.yamlを見る + + ```yaml + # pets-pet-id.yaml（API path 別ファイルの記載例） + get: + summary: FunctionID1 + description: Details for a pet + operationId: get-pets-pet-id + tags: + - pets + parameters: + - name: pet_id + in: path + description: The id of the pet to retrieve + schema: + type: string + required: true + responses: + "200": + description: Expected response to a valid request + content: + application/json: + schema: + type: object + properties: + pet_detail: + type: object + properties: + breeder: + type: string + date_of_birth: + type: string + format: date + pedigree: + type: object + properties: + registration_no: + type: integer + format: int64 + date_of_registration: + type: string + format: date + pedigree_image: + type: string + required: + - registration_no + - date_of_registration + - pedigree_image + required: + - pet_detail + examples: + ResExample1: + $ref: "../examples/pets_pet_id_get/res_example1.yaml" + "404": + $ref: "../openapi.yaml#/components/responses/NotFound" + "500": + $ref: "../openapi.yaml#/components/responses/InternalServerError" + ``` + +
+ +- OpenAPI の使用用途により、分割ファイルを1つのファイルにまとめる必要がある場合には、例えば[swagger-cli](https://apitools.dev/swagger-cli/)を使用して以下コマンドを実行する +- まとめたファイルは、以下のようになる（例: openapi.gen.yaml）。 + + ```bash + swagger-cli bundle openapi.yaml --outfile openapi.gen.yaml --type yaml + ``` + + +
+ openapi.gen.yamlを見る + + ```yaml + # openapi.gen.yaml（ファイルBundle後） + openapi: 3.0.3 + info: + version: 1.0.0 + title: Swagger Petstore + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + security: + - Bearer: [] + servers: + - url: 'http://petstore.swagger.io/v1' + tags: + - name: pets + description: Everything about your Pets + paths: + /pets: + get: + summary: FunctionID2 + description: List all pets + operationId: get-pets + tags: + - pets + parameters: + - name: limit + in: query + description: How many items to return at one time (max 100) + schema: + type: integer + maximum: 100 + format: int32 + required: false + 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: + type: object + properties: + pets: + type: array + maxItems: 100 + items: + type: object + 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 + required: + - id + - name + - category + - age + - sex + examples: + ResExample1: + value: + pets: + - 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: + pets: [] + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/InternalServerError' + post: + summary: FunctionID3 + description: Register a pet + operationId: post-pets + tags: + - pets + requestBody: + content: + application/json: + schema: + type: object + properties: + pet: + type: object + 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 + required: + - id + - name + - category + - age + - sex + required: + - pet + examples: + ReqExample1: + value: + pet: + id: 10005 + name: FrenchBulldog + category: dog + sub_category: FrenchBulldog + age: 1 + sex: male + note: friendly + tag: dog10005 + required: false + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + 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 + required: + - id + - name + - category + - age + - sex + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/InternalServerError' + '/pets/{pet_id}': + get: + summary: FunctionID1 + description: Details for a pet + operationId: get-pets-pet-id + tags: + - pets + parameters: + - name: pet_id + in: path + description: The id of the pet to retrieve + schema: + type: string + required: true + responses: + '200': + description: Expected response to a valid request + content: + application/json: + schema: + type: object + properties: + pet_detail: + type: object + properties: + breeder: + type: string + date_of_birth: + type: string + format: date + pedigree: + type: object + properties: + registration_no: + type: integer + format: int64 + date_of_registration: + type: string + format: date + pedigree_image: + type: string + required: + - registration_no + - date_of_registration + - pedigree_image + required: + - pet_detail + examples: + ResExample1: + value: + 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': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/InternalServerError' + components: + schemas: + Error: + type: object + properties: + code: + type: integer + format: int32 + message: + type: string + required: + - code + - message + responses: + NotFound: + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + InternalServerError: + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + securitySchemes: + Bearer: + type: http + scheme: bearer + bearerFormat: JWT + description: Authenthicaiton with bearer token + ``` + +
+ --- # License diff --git a/documents/forOpenAPISpecification/sample_divided/common/error.yaml b/documents/forOpenAPISpecification/sample_divided/common/error.yaml deleted file mode 100644 index df123b44..00000000 --- a/documents/forOpenAPISpecification/sample_divided/common/error.yaml +++ /dev/null @@ -1,10 +0,0 @@ -type: object -required: - - code - - message -properties: - code: - type: integer - format: int32 - message: - type: string \ No newline at end of file diff --git a/documents/forOpenAPISpecification/sample_divided/common/pet.yaml b/documents/forOpenAPISpecification/sample_divided/common/pet.yaml deleted file mode 100644 index b1d9086d..00000000 --- a/documents/forOpenAPISpecification/sample_divided/common/pet.yaml +++ /dev/null @@ -1,32 +0,0 @@ -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 \ No newline at end of file diff --git a/documents/forOpenAPISpecification/sample_divided/examples/pets_get/res_example1.yaml b/documents/forOpenAPISpecification/sample_divided/examples/pets_get/res_example1.yaml new file mode 100644 index 00000000..378e2849 --- /dev/null +++ b/documents/forOpenAPISpecification/sample_divided/examples/pets_get/res_example1.yaml @@ -0,0 +1,34 @@ +value: + pets: + - 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 diff --git a/documents/forOpenAPISpecification/sample_divided/examples/pets_get/res_example2.yaml b/documents/forOpenAPISpecification/sample_divided/examples/pets_get/res_example2.yaml new file mode 100644 index 00000000..8b00e7ef --- /dev/null +++ b/documents/forOpenAPISpecification/sample_divided/examples/pets_get/res_example2.yaml @@ -0,0 +1,2 @@ +value: + pets: [] diff --git a/documents/forOpenAPISpecification/sample_divided/examples/pets_pet_id_get/res_example1.yaml b/documents/forOpenAPISpecification/sample_divided/examples/pets_pet_id_get/res_example1.yaml new file mode 100644 index 00000000..04dc7697 --- /dev/null +++ b/documents/forOpenAPISpecification/sample_divided/examples/pets_pet_id_get/res_example1.yaml @@ -0,0 +1,8 @@ +value: + pet_detail: + breeder: BreederName + date_of_birth: '2023-10-31' + pedigree: + registration_no: 11111111 + date_of_registration: '2023-10-31' + pedigree_image: 9j2wBDAA...8QAPxAAAQQABAMGBAYDAAEDAg diff --git a/documents/forOpenAPISpecification/sample_divided/examples/pets_post/req_example1.yaml b/documents/forOpenAPISpecification/sample_divided/examples/pets_post/req_example1.yaml new file mode 100644 index 00000000..25873fb6 --- /dev/null +++ b/documents/forOpenAPISpecification/sample_divided/examples/pets_post/req_example1.yaml @@ -0,0 +1,10 @@ +value: + pet: + id: 10005 + name: FrenchBulldog + category: dog + sub_category: FrenchBulldog + age: 1 + sex: male + note: friendly + tag: dog10005 diff --git a/documents/forOpenAPISpecification/sample_divided/openapi.gen.yaml b/documents/forOpenAPISpecification/sample_divided/openapi.gen.yaml index 3875d989..9850d581 100644 --- a/documents/forOpenAPISpecification/sample_divided/openapi.gen.yaml +++ b/documents/forOpenAPISpecification/sample_divided/openapi.gen.yaml @@ -3,7 +3,10 @@ info: version: 1.0.0 title: Swagger Petstore license: - name: MIT + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' +security: + - Bearer: [] servers: - url: 'http://petstore.swagger.io/v1' tags: @@ -12,7 +15,8 @@ tags: paths: /pets: get: - summary: List all pets + summary: FunctionID2 + description: List all pets operationId: get-pets tags: - pets @@ -20,11 +24,11 @@ paths: - name: limit in: query description: How many items to return at one time (max 100) - required: false schema: type: integer maximum: 100 format: int32 + required: false responses: '200': description: A paged array of pets @@ -36,61 +40,90 @@ paths: content: application/json: schema: - type: array - maxItems: 100 - items: - $ref: '#/components/schemas/Pet' + type: object + properties: + pets: + type: array + maxItems: 100 + items: + type: object + 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 + required: + - id + - name + - category + - age + - sex 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 + pets: + - 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: [] + value: + pets: [] '404': - description: not found error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + $ref: '#/components/responses/NotFound' '500': - description: unexpected error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + $ref: '#/components/responses/InternalServerError' post: - summary: Register a pet + summary: FunctionID3 + description: Register a pet operationId: post-pets tags: - pets @@ -98,12 +131,43 @@ paths: content: application/json: schema: - required: - - pet type: object properties: pet: - $ref: '#/components/schemas/Pet' + type: object + 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 + required: + - id + - name + - category + - age + - sex + required: + - pet examples: ReqExample1: value: @@ -118,60 +182,97 @@ paths: tag: dog10005 required: false responses: - '201': - description: Null response - '404': - description: not found error + '200': + description: OK content: application/json: schema: - $ref: '#/components/schemas/Error' + type: object + 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 + required: + - id + - name + - category + - age + - sex + '404': + $ref: '#/components/responses/NotFound' '500': - description: unexpected error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' - '/pets/{petId}': + $ref: '#/components/responses/InternalServerError' + '/pets/{pet_id}': get: - summary: Details for a pet + summary: FunctionID1 + description: Details for a pet operationId: get-pets-pet-id tags: - pets parameters: - - name: petId + - name: pet_id in: path - required: true description: The id of the pet to retrieve schema: type: string + required: true responses: '200': description: Expected response to a valid request content: application/json: schema: - required: - - pet - - pet_detail type: object properties: - pet: - $ref: '#/components/schemas/Pet' pet_detail: - $ref: '#/components/schemas/PetDetail' + type: object + properties: + breeder: + type: string + date_of_birth: + type: string + format: date + pedigree: + type: object + properties: + registration_no: + type: integer + format: int64 + date_of_registration: + type: string + format: date + pedigree_image: + type: string + required: + - registration_no + - date_of_registration + - pedigree_image + required: + - pet_detail 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' @@ -180,85 +281,38 @@ paths: date_of_registration: '2023-10-31' pedigree_image: 9j2wBDAA...8QAPxAAAQQABAMGBAYDAAEDAg '404': - description: not found error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + $ref: '#/components/responses/NotFound' '500': - description: unexpected error - content: - application/json: - schema: - $ref: '#/components/schemas/Error' + $ref: '#/components/responses/InternalServerError' components: schemas: - 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 + required: + - code + - message + responses: + NotFound: + description: Not Found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + InternalServerError: + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + securitySchemes: + Bearer: + type: http + scheme: bearer + bearerFormat: JWT + description: Authenthicaiton with bearer token diff --git a/documents/forOpenAPISpecification/sample_divided/openapi.yaml b/documents/forOpenAPISpecification/sample_divided/openapi.yaml index 3d7f1478..6ae8510e 100644 --- a/documents/forOpenAPISpecification/sample_divided/openapi.yaml +++ b/documents/forOpenAPISpecification/sample_divided/openapi.yaml @@ -2,8 +2,11 @@ openapi: "3.0.3" info: version: 1.0.0 title: Swagger Petstore - license: - name: MIT + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html +security: + - Bearer: [] servers: - url: http://petstore.swagger.io/v1 tags: @@ -11,20 +14,39 @@ tags: description: Everything about your Pets paths: /pets: - get: - $ref: "./pets_get/pets_get.yaml#/operation" - post: - $ref: "./pets_post/pets_post.yaml#/operation" - /pets/{petId}: - get: - $ref: "./pets-pet-id_get/pets-pet-id_get.yaml#/operation" + $ref: "./pets/pets.yaml" + /pets/{pet_id}: + $ref: "./pets/pets_pet_id.yaml" + components: schemas: - PetDetail: - $ref: "./pets-pet-id_get/pets-pet-id_get.yaml#/components/schemas/PetDetail" - Pedigree: - $ref: "./pets-pet-id_get/pets-pet-id_get.yaml#/components/schemas/Pedigree" - Pet: - $ref: "./common/pet.yaml" Error: - $ref: "./common/error.yaml" \ No newline at end of file + type: object + properties: + code: + type: integer + format: int32 + message: + type: string + required: + - code + - message + responses: + NotFound: + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + InternalServerError: + description: Internal Server Error + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + securitySchemes: + Bearer: + type: http + scheme: bearer + bearerFormat: JWT + description: 'Authenthicaiton with bearer token' diff --git a/documents/forOpenAPISpecification/sample_divided/pets-pet-id_get/examples/res_example1.yaml b/documents/forOpenAPISpecification/sample_divided/pets-pet-id_get/examples/res_example1.yaml deleted file mode 100644 index 7c9b93a9..00000000 --- a/documents/forOpenAPISpecification/sample_divided/pets-pet-id_get/examples/res_example1.yaml +++ /dev/null @@ -1,16 +0,0 @@ -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 \ No newline at end of file diff --git a/documents/forOpenAPISpecification/sample_divided/pets-pet-id_get/pets-pet-id_get.yaml b/documents/forOpenAPISpecification/sample_divided/pets-pet-id_get/pets-pet-id_get.yaml deleted file mode 100644 index 8b8da580..00000000 --- a/documents/forOpenAPISpecification/sample_divided/pets-pet-id_get/pets-pet-id_get.yaml +++ /dev/null @@ -1,73 +0,0 @@ -operation: - 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/responses/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" -components: - schemas: - 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 - responses: - ResPetsPetIdGet: - required: - - pet - - pet_detail - type: object - properties: - pet: - $ref: "../common/pet.yaml" - pet_detail: - $ref: "#/components/schemas/PetDetail" \ No newline at end of file diff --git a/documents/forOpenAPISpecification/sample_divided/pets/pets.yaml b/documents/forOpenAPISpecification/sample_divided/pets/pets.yaml new file mode 100644 index 00000000..f201a6db --- /dev/null +++ b/documents/forOpenAPISpecification/sample_divided/pets/pets.yaml @@ -0,0 +1,167 @@ +get: + summary: FunctionID2 + description: List all pets + operationId: get-pets + tags: + - pets + parameters: + - name: limit + in: query + description: How many items to return at one time (max 100) + schema: + type: integer + maximum: 100 + format: int32 + required: false + 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: + type: object + properties: + pets: + type: array + maxItems: 100 + items: + type: object + 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 + required: + - id + - name + - category + - age + - sex + examples: + ResExample1: + $ref: "../examples/pets_get/res_example1.yaml" + ResExample2: + $ref: "../examples/pets_get/res_example2.yaml" + "404": + $ref: "../openapi.yaml#/components/responses/NotFound" + "500": + $ref: "../openapi.yaml#/components/responses/InternalServerError" + +post: + summary: FunctionID3 + description: Register a pet + operationId: post-pets + tags: + - pets + requestBody: + content: + application/json: + schema: + type: object + properties: + pet: + type: object + 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 + required: + - id + - name + - category + - age + - sex + required: + - pet + examples: + ReqExample1: + $ref: "../examples/pets_post/req_example1.yaml" + required: false + responses: + "200": + description: OK + content: + application/json: + schema: + type: object + 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 + required: + - id + - name + - category + - age + - sex + "404": + $ref: "../openapi.yaml#/components/responses/NotFound" + "500": + $ref: "../openapi.yaml#/components/responses/InternalServerError" diff --git a/documents/forOpenAPISpecification/sample_divided/pets/pets_pet_id.yaml b/documents/forOpenAPISpecification/sample_divided/pets/pets_pet_id.yaml new file mode 100644 index 00000000..c048e169 --- /dev/null +++ b/documents/forOpenAPISpecification/sample_divided/pets/pets_pet_id.yaml @@ -0,0 +1,53 @@ +get: + summary: FunctionID1 + description: Details for a pet + operationId: get-pets-pet-id + tags: + - pets + parameters: + - name: pet_id + in: path + description: The id of the pet to retrieve + schema: + type: string + required: true + responses: + "200": + description: Expected response to a valid request + content: + application/json: + schema: + type: object + properties: + pet_detail: + type: object + properties: + breeder: + type: string + date_of_birth: + type: string + format: date + pedigree: + type: object + properties: + registration_no: + type: integer + format: int64 + date_of_registration: + type: string + format: date + pedigree_image: + type: string + required: + - registration_no + - date_of_registration + - pedigree_image + required: + - pet_detail + examples: + ResExample1: + $ref: "../examples/pets_pet_id_get/res_example1.yaml" + "404": + $ref: "../openapi.yaml#/components/responses/NotFound" + "500": + $ref: "../openapi.yaml#/components/responses/InternalServerError" diff --git a/documents/forOpenAPISpecification/sample_divided/pets_get/examples/res_example1.yaml b/documents/forOpenAPISpecification/sample_divided/pets_get/examples/res_example1.yaml deleted file mode 100644 index 8199a157..00000000 --- a/documents/forOpenAPISpecification/sample_divided/pets_get/examples/res_example1.yaml +++ /dev/null @@ -1,32 +0,0 @@ -- 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 \ No newline at end of file diff --git a/documents/forOpenAPISpecification/sample_divided/pets_get/examples/res_example2.yaml b/documents/forOpenAPISpecification/sample_divided/pets_get/examples/res_example2.yaml deleted file mode 100644 index 0637a088..00000000 --- a/documents/forOpenAPISpecification/sample_divided/pets_get/examples/res_example2.yaml +++ /dev/null @@ -1 +0,0 @@ -[] \ No newline at end of file diff --git a/documents/forOpenAPISpecification/sample_divided/pets_get/pets_get.yaml b/documents/forOpenAPISpecification/sample_divided/pets_get/pets_get.yaml deleted file mode 100644 index 4082c580..00000000 --- a/documents/forOpenAPISpecification/sample_divided/pets_get/pets_get.yaml +++ /dev/null @@ -1,53 +0,0 @@ -operation: - 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/responses/ResPetsGet" - examples: - ResExample1: - value: - $ref: "./examples/res_example1.yaml" - ResExample2: - value: - $ref: "./examples/res_example2.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" - -components: - responses: - ResPetsGet: - type: array - maxItems: 100 - items: - $ref: "../common/pet.yaml" \ No newline at end of file diff --git a/documents/forOpenAPISpecification/sample_divided/pets_post/examples/req_example1.yaml b/documents/forOpenAPISpecification/sample_divided/pets_post/examples/req_example1.yaml deleted file mode 100644 index 2588566e..00000000 --- a/documents/forOpenAPISpecification/sample_divided/pets_post/examples/req_example1.yaml +++ /dev/null @@ -1,9 +0,0 @@ -pet: - id: 10005 - name: FrenchBulldog - category: dog - sub_category: FrenchBulldog - age: 1 - sex: male - note: friendly - tag: dog10005 diff --git a/documents/forOpenAPISpecification/sample_divided/pets_post/pets_post.yaml b/documents/forOpenAPISpecification/sample_divided/pets_post/pets_post.yaml deleted file mode 100644 index b289a081..00000000 --- a/documents/forOpenAPISpecification/sample_divided/pets_post/pets_post.yaml +++ /dev/null @@ -1,40 +0,0 @@ -operation: - summary: Register a pet - operationId: post-pets - tags: - - pets - requestBody: - content: - application/json: - schema: - $ref: "#/components/responses/ReqPetsPost" - examples: - ReqExample1: - value: - $ref: "./examples/req_example1.yaml" - required: false - responses: - "201": - description: Null response - "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" - -components: - responses: - ReqPetsPost: - required: - - pet - type: object - properties: - pet: - $ref: "../common/pet.yaml" \ No newline at end of file From 7ae2612c06df397a186102275e3d80cc290f6d34 Mon Sep 17 00:00:00 2001 From: future-fujita Date: Wed, 18 Sep 2024 02:22:15 +0900 Subject: [PATCH 2/3] fix: reflect review comments --- .../OpenAPI_Specification_3.0.3.md | 234 ++++++++---------- .../sample_divided/common/responses.yaml | 26 ++ .../{res_example1.yaml => test_case_001.yaml} | 0 .../{res_example2.yaml => test_case_002.yaml} | 0 .../{res_example1.yaml => test_case_003.yaml} | 0 .../{req_example1.yaml => test_case_004.yaml} | 0 .../sample_divided/openapi.gen.yaml | 172 ++++++------- .../sample_divided/openapi.yaml | 28 --- .../sample_divided/pets/pets.yaml | 34 +-- .../sample_divided/pets/pets_pet_id.yaml | 14 +- 10 files changed, 247 insertions(+), 261 deletions(-) create mode 100644 documents/forOpenAPISpecification/sample_divided/common/responses.yaml rename documents/forOpenAPISpecification/sample_divided/examples/pets_get/{res_example1.yaml => test_case_001.yaml} (100%) rename documents/forOpenAPISpecification/sample_divided/examples/pets_get/{res_example2.yaml => test_case_002.yaml} (100%) rename documents/forOpenAPISpecification/sample_divided/examples/pets_pet_id_get/{res_example1.yaml => test_case_003.yaml} (100%) rename documents/forOpenAPISpecification/sample_divided/examples/pets_post/{req_example1.yaml => test_case_004.yaml} (100%) diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index 645a4538..38ef3800 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -1191,12 +1191,16 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 1. API path ごとに設計担当者を分けて、それぞれに OpenAPI を編集する場合は、path の単位で分割する。 2. テストツールとして [stoplightio/prism](https://github.com/stoplightio/prism)を使用する場合、テストケースごとにデータファイルを作成して、`examples` にファイルパスを指定する。 +注意点: +- OpenAPI 仕様上、`$ref` は[利用できる箇所が限定されている](https://swagger.io/docs/specification/using-ref/#allowed-places)ことに注意する + - 例えば[Path](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#path-item-object)は `$ref` が利用可能だが、[Operation](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object)（HTTPメソッドの粒度）では利用不可である + ### サンプル説明 分割方法 1, 2 の両方に当てはまる場合のサンプルを用いて説明する。`openapi.yaml` とディレクトリ構成は下の通り。全量は [sample_divided](https://github.com/future-architect/coding-standards/tree/master/documents/forOpenAPISpecification/sample_divided)を参照すること。 - リソース単位にディレクトリを作成して、path ごとに定義ファイルを格納する。 -- `components` の schemas モデルは、大本の openapi.yaml に命名の定義を記載する。モデルの中身は別ファイルとして切り出すことも可能である。 +- `components` の schemas モデルの中身は別ファイルとして切り出すことが可能である。 ```yaml # openapi.yaml（ファイル分割例） @@ -1204,9 +1208,6 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 info: version: 1.0.0 title: Swagger Petstore - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html security: - Bearer: [] servers: @@ -1221,31 +1222,6 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 $ref: "./pets/pets_pet_id.yaml" components: - schemas: - Error: - type: object - properties: - code: - type: integer - format: int32 - message: - type: string - required: - - code - - message - responses: - NotFound: - description: Not Found - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - InternalServerError: - description: Internal Server Error - content: - application/json: - schema: - $ref: "#/components/schemas/Error" securitySchemes: Bearer: type: http @@ -1262,14 +1238,14 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 │ ├─examples │ ├─pets_get - │ │ ├─res_example1.yaml - │ │ └─res_example2.yaml + │ │ ├─test_case_001.yaml + │ │ └─test_case_002.yaml │ │ │ ├─pets_pet_id_get - │ │ └─res_example1.yaml + │ │ └─test_case_003.yaml │ │ │ └─pets_post - │ └─req_example1.yaml + │ └─test_case_004.yaml │ └─pets ├─pets.yaml @@ -1277,7 +1253,7 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 ``` - `openapi.yaml` の `paths` に記載した API ファイルは以下のように作成する（例: pets-pet-id.yaml）。 -- `examples` には、各 API のテストケース ID をキーとして指定（`ResExample1`）し、該当するテストケースのデータファイルパスを参照させる。ファイル名は、指定したキーをスネークケースに変換したものを使用するとよい。 +- `examples` には、例えば各 API のテストケース ID をキーとして指定（`TestCase003`）し、該当するテストケースのデータファイルパスを参照させる。
pets-pet-id.yamlを見る @@ -1285,9 +1261,9 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 ```yaml # pets-pet-id.yaml（API path 別ファイルの記載例） get: - summary: FunctionID1 - description: Details for a pet - operationId: get-pets-pet-id + summary: Get details of a pet + description: Get details of a pet by specifying its pet ID. + operationId: getPetsPetId tags: - pets parameters: @@ -1331,21 +1307,21 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 required: - pet_detail examples: - ResExample1: - $ref: "../examples/pets_pet_id_get/res_example1.yaml" + TestCase003: + $ref: "../examples/pets_pet_id_get/test_case_003.yaml" "404": - $ref: "../openapi.yaml#/components/responses/NotFound" + $ref: "../common/responses.yaml#/components/responses/NotFound" "500": - $ref: "../openapi.yaml#/components/responses/InternalServerError" + $ref: "../common/responses.yaml#/components/responses/InternalServerError" ```
-- OpenAPI の使用用途により、分割ファイルを1つのファイルにまとめる必要がある場合には、例えば[swagger-cli](https://apitools.dev/swagger-cli/)を使用して以下コマンドを実行する +- OpenAPI の使用用途により、分割ファイルを1つのファイルにまとめる必要がある場合には、例えば[Redocly CLI](https://redocly.com/redocly-cli)を使用して以下コマンドを実行する - まとめたファイルは、以下のようになる（例: openapi.gen.yaml）。 ```bash - swagger-cli bundle openapi.yaml --outfile openapi.gen.yaml --type yaml + redocly bundle openapi.yaml --output openapi.gen.yaml ``` @@ -1358,22 +1334,19 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 info: version: 1.0.0 title: Swagger Petstore - license: - name: Apache 2.0 - url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + servers: + - url: http://petstore.swagger.io/v1 security: - Bearer: [] - servers: - - url: 'http://petstore.swagger.io/v1' tags: - name: pets description: Everything about your Pets paths: /pets: get: - summary: FunctionID2 - description: List all pets - operationId: get-pets + summary: Search a pet list + description: Search a list of registered pets up to 100. + operationId: getPets tags: - pets parameters: @@ -1435,52 +1408,18 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 - age - sex examples: - ResExample1: - value: - pets: - - 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: - pets: [] + TestCase001: + $ref: '#/components/examples/test_case_001' + TestCase002: + $ref: '#/components/examples/test_case_002' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' post: - summary: FunctionID3 - description: Register a pet - operationId: post-pets + summary: Register a pet + description: Reginster basic information of new pet. + operationId: postPets tags: - pets requestBody: @@ -1525,18 +1464,9 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 required: - pet examples: - ReqExample1: - value: - pet: - id: 10005 - name: FrenchBulldog - category: dog - sub_category: FrenchBulldog - age: 1 - sex: male - note: friendly - tag: dog10005 - required: false + TestCase004: + $ref: '#/components/examples/test_case_004' + required: true responses: '200': description: OK @@ -1579,11 +1509,11 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' - '/pets/{pet_id}': + /pets/{pet_id}: get: - summary: FunctionID1 - description: Details for a pet - operationId: get-pets-pet-id + summary: Get details of a pet + description: Get details of a pet by specifying its pet ID. + operationId: getPetsPetId tags: - pets parameters: @@ -1627,22 +1557,80 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 required: - pet_detail examples: - ResExample1: - value: - pet_detail: - breeder: BreederName - date_of_birth: '2023-10-31' - pedigree: - registration_no: 11111111 - date_of_registration: '2023-10-31' - pedigree_image: 9j2wBDAA...8QAPxAAAQQABAMGBAYDAAEDAg + TestCase003: + $ref: '#/components/examples/test_case_003' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: + securitySchemes: + Bearer: + type: http + scheme: bearer + bearerFormat: JWT + description: Authenthicaiton with bearer token + examples: + test_case_001: + value: + pets: + - 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 + test_case_002: + value: + pets: [] + test_case_004: + value: + pet: + id: 10005 + name: FrenchBulldog + category: dog + sub_category: FrenchBulldog + age: 1 + sex: male + note: friendly + tag: dog10005 + test_case_003: + value: + pet_detail: + breeder: BreederName + date_of_birth: '2023-10-31' + pedigree: + registration_no: 11111111 + date_of_registration: '2023-10-31' + pedigree_image: 9j2wBDAA...8QAPxAAAQQABAMGBAYDAAEDAg schemas: - Error: + ProblemDetailError: type: object properties: code: @@ -1659,19 +1647,13 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数 content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: '#/components/schemas/ProblemDetailError' InternalServerError: description: Internal Server Error content: application/json: schema: - $ref: '#/components/schemas/Error' - securitySchemes: - Bearer: - type: http - scheme: bearer - bearerFormat: JWT - description: Authenthicaiton with bearer token + $ref: '#/components/schemas/ProblemDetailError' ``` diff --git a/documents/forOpenAPISpecification/sample_divided/common/responses.yaml b/documents/forOpenAPISpecification/sample_divided/common/responses.yaml new file mode 100644 index 00000000..d558f58c --- /dev/null +++ b/documents/forOpenAPISpecification/sample_divided/common/responses.yaml @@ -0,0 +1,26 @@ +components: + schemas: + ProblemDetailError: + type: object + properties: + code: + type: integer + format: int32 + message: + type: string + required: + - code + - message + responses: + NotFound: + description: Not Found + content: + application/json: + schema: + $ref: "#/components/schemas/ProblemDetailError" + InternalServerError: + description: Internal Server Error + content: + application/json: + schema: + $ref: "#/components/schemas/ProblemDetailError" \ No newline at end of file diff --git a/documents/forOpenAPISpecification/sample_divided/examples/pets_get/res_example1.yaml b/documents/forOpenAPISpecification/sample_divided/examples/pets_get/test_case_001.yaml similarity index 100% rename from documents/forOpenAPISpecification/sample_divided/examples/pets_get/res_example1.yaml rename to documents/forOpenAPISpecification/sample_divided/examples/pets_get/test_case_001.yaml diff --git a/documents/forOpenAPISpecification/sample_divided/examples/pets_get/res_example2.yaml b/documents/forOpenAPISpecification/sample_divided/examples/pets_get/test_case_002.yaml similarity index 100% rename from documents/forOpenAPISpecification/sample_divided/examples/pets_get/res_example2.yaml rename to documents/forOpenAPISpecification/sample_divided/examples/pets_get/test_case_002.yaml diff --git a/documents/forOpenAPISpecification/sample_divided/examples/pets_pet_id_get/res_example1.yaml b/documents/forOpenAPISpecification/sample_divided/examples/pets_pet_id_get/test_case_003.yaml similarity index 100% rename from documents/forOpenAPISpecification/sample_divided/examples/pets_pet_id_get/res_example1.yaml rename to documents/forOpenAPISpecification/sample_divided/examples/pets_pet_id_get/test_case_003.yaml diff --git a/documents/forOpenAPISpecification/sample_divided/examples/pets_post/req_example1.yaml b/documents/forOpenAPISpecification/sample_divided/examples/pets_post/test_case_004.yaml similarity index 100% rename from documents/forOpenAPISpecification/sample_divided/examples/pets_post/req_example1.yaml rename to documents/forOpenAPISpecification/sample_divided/examples/pets_post/test_case_004.yaml diff --git a/documents/forOpenAPISpecification/sample_divided/openapi.gen.yaml b/documents/forOpenAPISpecification/sample_divided/openapi.gen.yaml index 9850d581..b25173c9 100644 --- a/documents/forOpenAPISpecification/sample_divided/openapi.gen.yaml +++ b/documents/forOpenAPISpecification/sample_divided/openapi.gen.yaml @@ -2,22 +2,19 @@ openapi: 3.0.3 info: version: 1.0.0 title: Swagger Petstore - license: - name: Apache 2.0 - url: 'https://www.apache.org/licenses/LICENSE-2.0.html' +servers: + - url: http://petstore.swagger.io/v1 security: - Bearer: [] -servers: - - url: 'http://petstore.swagger.io/v1' tags: - name: pets description: Everything about your Pets paths: /pets: get: - summary: FunctionID2 - description: List all pets - operationId: get-pets + summary: Search a pet list + description: Search a list of registered pets up to 100. + operationId: getPets tags: - pets parameters: @@ -79,52 +76,18 @@ paths: - age - sex examples: - ResExample1: - value: - pets: - - 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: - pets: [] + TestCase001: + $ref: '#/components/examples/test_case_001' + TestCase002: + $ref: '#/components/examples/test_case_002' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' post: - summary: FunctionID3 - description: Register a pet - operationId: post-pets + summary: Register a pet + description: Reginster basic information of new pet. + operationId: postPets tags: - pets requestBody: @@ -169,18 +132,9 @@ paths: required: - pet examples: - ReqExample1: - value: - pet: - id: 10005 - name: FrenchBulldog - category: dog - sub_category: FrenchBulldog - age: 1 - sex: male - note: friendly - tag: dog10005 - required: false + TestCase004: + $ref: '#/components/examples/test_case_004' + required: true responses: '200': description: OK @@ -223,11 +177,11 @@ paths: $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' - '/pets/{pet_id}': + /pets/{pet_id}: get: - summary: FunctionID1 - description: Details for a pet - operationId: get-pets-pet-id + summary: Get details of a pet + description: Get details of a pet by specifying its pet ID. + operationId: getPetsPetId tags: - pets parameters: @@ -271,22 +225,80 @@ paths: required: - pet_detail examples: - ResExample1: - value: - pet_detail: - breeder: BreederName - date_of_birth: '2023-10-31' - pedigree: - registration_no: 11111111 - date_of_registration: '2023-10-31' - pedigree_image: 9j2wBDAA...8QAPxAAAQQABAMGBAYDAAEDAg + TestCase003: + $ref: '#/components/examples/test_case_003' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: + securitySchemes: + Bearer: + type: http + scheme: bearer + bearerFormat: JWT + description: Authenthicaiton with bearer token + examples: + test_case_001: + value: + pets: + - 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 + test_case_002: + value: + pets: [] + test_case_004: + value: + pet: + id: 10005 + name: FrenchBulldog + category: dog + sub_category: FrenchBulldog + age: 1 + sex: male + note: friendly + tag: dog10005 + test_case_003: + value: + pet_detail: + breeder: BreederName + date_of_birth: '2023-10-31' + pedigree: + registration_no: 11111111 + date_of_registration: '2023-10-31' + pedigree_image: 9j2wBDAA...8QAPxAAAQQABAMGBAYDAAEDAg schemas: - Error: + ProblemDetailError: type: object properties: code: @@ -303,16 +315,10 @@ components: content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: '#/components/schemas/ProblemDetailError' InternalServerError: description: Internal Server Error content: application/json: schema: - $ref: '#/components/schemas/Error' - securitySchemes: - Bearer: - type: http - scheme: bearer - bearerFormat: JWT - description: Authenthicaiton with bearer token + $ref: '#/components/schemas/ProblemDetailError' diff --git a/documents/forOpenAPISpecification/sample_divided/openapi.yaml b/documents/forOpenAPISpecification/sample_divided/openapi.yaml index 6ae8510e..b60f2c39 100644 --- a/documents/forOpenAPISpecification/sample_divided/openapi.yaml +++ b/documents/forOpenAPISpecification/sample_divided/openapi.yaml @@ -2,9 +2,6 @@ openapi: "3.0.3" info: version: 1.0.0 title: Swagger Petstore - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html security: - Bearer: [] servers: @@ -19,31 +16,6 @@ paths: $ref: "./pets/pets_pet_id.yaml" components: - schemas: - Error: - type: object - properties: - code: - type: integer - format: int32 - message: - type: string - required: - - code - - message - responses: - NotFound: - description: Not Found - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - InternalServerError: - description: Internal Server Error - content: - application/json: - schema: - $ref: "#/components/schemas/Error" securitySchemes: Bearer: type: http diff --git a/documents/forOpenAPISpecification/sample_divided/pets/pets.yaml b/documents/forOpenAPISpecification/sample_divided/pets/pets.yaml index f201a6db..fe463158 100644 --- a/documents/forOpenAPISpecification/sample_divided/pets/pets.yaml +++ b/documents/forOpenAPISpecification/sample_divided/pets/pets.yaml @@ -1,7 +1,7 @@ get: - summary: FunctionID2 - description: List all pets - operationId: get-pets + summary: Search a pet list + description: Search a list of registered pets up to 100. + operationId: getPets tags: - pets parameters: @@ -63,19 +63,19 @@ get: - age - sex examples: - ResExample1: - $ref: "../examples/pets_get/res_example1.yaml" - ResExample2: - $ref: "../examples/pets_get/res_example2.yaml" + TestCase001: + $ref: "../examples/pets_get/test_case_001.yaml" + TestCase002: + $ref: "../examples/pets_get/test_case_002.yaml" "404": - $ref: "../openapi.yaml#/components/responses/NotFound" + $ref: "../common/responses.yaml#/components/responses/NotFound" "500": - $ref: "../openapi.yaml#/components/responses/InternalServerError" + $ref: "../common/responses.yaml#/components/responses/InternalServerError" post: - summary: FunctionID3 - description: Register a pet - operationId: post-pets + summary: Register a pet + description: Reginster basic information of new pet. + operationId: postPets tags: - pets requestBody: @@ -120,9 +120,9 @@ post: required: - pet examples: - ReqExample1: - $ref: "../examples/pets_post/req_example1.yaml" - required: false + TestCase004: + $ref: "../examples/pets_post/test_case_004.yaml" + required: true responses: "200": description: OK @@ -162,6 +162,6 @@ post: - age - sex "404": - $ref: "../openapi.yaml#/components/responses/NotFound" + $ref: "../common/responses.yaml#/components/responses/NotFound" "500": - $ref: "../openapi.yaml#/components/responses/InternalServerError" + $ref: "../common/responses.yaml#/components/responses/InternalServerError" diff --git a/documents/forOpenAPISpecification/sample_divided/pets/pets_pet_id.yaml b/documents/forOpenAPISpecification/sample_divided/pets/pets_pet_id.yaml index c048e169..5079d376 100644 --- a/documents/forOpenAPISpecification/sample_divided/pets/pets_pet_id.yaml +++ b/documents/forOpenAPISpecification/sample_divided/pets/pets_pet_id.yaml @@ -1,7 +1,7 @@ get: - summary: FunctionID1 - description: Details for a pet - operationId: get-pets-pet-id + summary: Get details of a pet + description: Get details of a pet by specifying its pet ID. + operationId: getPetsPetId tags: - pets parameters: @@ -45,9 +45,9 @@ get: required: - pet_detail examples: - ResExample1: - $ref: "../examples/pets_pet_id_get/res_example1.yaml" + TestCase003: + $ref: "../examples/pets_pet_id_get/test_case_003.yaml" "404": - $ref: "../openapi.yaml#/components/responses/NotFound" + $ref: "../common/responses.yaml#/components/responses/NotFound" "500": - $ref: "../openapi.yaml#/components/responses/InternalServerError" + $ref: "../common/responses.yaml#/components/responses/InternalServerError" From 0e0633ad494fce15ebe5b7c83e8479dd479beef9 Mon Sep 17 00:00:00 2001 From: Junki Mano Date: Wed, 18 Sep 2024 16:52:28 +0900 Subject: [PATCH 3/3] Update documents/forOpenAPISpecification/sample_divided/common/responses.yaml --- .../sample_divided/common/responses.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/forOpenAPISpecification/sample_divided/common/responses.yaml b/documents/forOpenAPISpecification/sample_divided/common/responses.yaml index d558f58c..3ea23551 100644 --- a/documents/forOpenAPISpecification/sample_divided/common/responses.yaml +++ b/documents/forOpenAPISpecification/sample_divided/common/responses.yaml @@ -23,4 +23,4 @@ components: content: application/json: schema: - $ref: "#/components/schemas/ProblemDetailError" \ No newline at end of file + $ref: "#/components/schemas/ProblemDetailError"