diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md
index 8b5cf03d..de965978 100644
--- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md
+++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md
@@ -1246,28 +1246,31 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数
name: MIT
servers:
- url: http://petstore.swagger.io/v1
+ tags:
+ - name: pets
+ description: Everything about your Pets
paths:
/pets:
get:
- $ref: "./pets_get/pets_get.yaml"
+ $ref: "./pets_get/pets_get.yaml#/operation"
post:
- $ref: "./pets_post/pets_post.yaml"
+ $ref: "./pets_post/pets_post.yaml#/operation"
/pets/{petId}:
get:
- $ref: "./pets-pet-id_get/pets-pet-id_get.yaml"
+ $ref: "./pets-pet-id_get/pets-pet-id_get.yaml#/operation"
components:
schemas:
ResPetsGet:
- $ref: "./pets_get/response.yaml"
+ $ref: "./pets_get/pets_get.yaml#/components/schemas/ResPetsGet"
ReqPetsPost:
- $ref: "./pets_post/request.yaml"
+ $ref: "./pets_post/pets_post.yaml#/components/schemas/ReqPetsPost"
ResPetsPetIdGet:
- $ref: "./pets-pet-id_get/response.yaml#/ResPetsPetIdGet"
+ $ref: "./pets-pet-id_get/pets-pet-id_get.yaml#/components/schemas/ResPetsPetIdGet"
PetDetail:
- $ref: "./pets-pet-id_get/response.yaml#/PetDetail"
+ $ref: "./pets-pet-id_get/pets-pet-id_get.yaml#/components/schemas/PetDetail"
Pedigree:
- $ref: "./pets-pet-id_get/response.yaml#/Pedigree"
+ $ref: "./pets-pet-id_get/pets-pet-id_get.yaml#/components/schemas/Pedigree"
Pet:
$ref: "./common/pet.yaml"
Error:
@@ -1280,132 +1283,118 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数
ファイル分割例: ディレクトリ構成
```sh
- │ openapi.gen.yaml
- │ openapi.yaml
+ ├─openapi.gen.yaml
+ ├─openapi.yaml
│
├─common
- │ error.yaml
- │ pet.yaml
+ │ ├─error.yaml
+ │ └─pet.yaml
│
├─pets-pet-id_get
- │ │ pets-pet-id_get.yaml
- │ │ response.yaml
- │ │
+ │ ├─pets-pet-id_get.yaml
│ └─examples
- │ res_example1.yaml
+ │ └─res_example1.yaml
│
├─pets_get
- │ │ pets_get.yaml
- │ │ response.yaml
- │ │
+ │ ├─pets_get.yaml
│ └─examples
- │ res_example1.yaml
- │ res_example2.yaml
+ │ ├─res_example1.yaml
+ │ └─res_example2.yaml
│
└─pets_post
- │ pets_post.yaml
- │ request.yaml
- │
+ ├─pets_post.yaml
└─examples
- req_example1.yaml
+ └─req_example1.yaml
```
-- `openapi.yaml` の `paths` に記載したAPIファイルは以下のように作成する。`schema` にて `openapi.yaml` に指定したキー(`../openapi.yaml#/components/schemas/ResPetsPetIdGet`)を参照する。
+- `openapi.yaml` の `paths` に記載したAPIファイルは以下のように作成する。
+- 複数API間に共通のモデルについては `openapi.yaml` に指定したキー(`../openapi.yaml#/components/schemas/Pet`)を参照する。
- `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
+ 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/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"
- ```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
+ components:
+ schemas:
+ ResPetsPetIdGet:
+ required:
+ - pet
+ - pet_detail
+ type: object
+ properties:
+ pet:
+ $ref: "../openapi.yaml#/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
```
+
- OpenAPIの使用用途により、分割ファイルを1つのファイルにまとめる必要がある場合には、例えば[swagger-cli](https://apitools.dev/swagger-cli/)を使用して以下コマンドを実行する。
```bash
@@ -1424,6 +1413,9 @@ OpenAPI ドキュメントは単一のファイルで構成することも複数
name: MIT
servers:
- url: 'http://petstore.swagger.io/v1'
+ tags:
+ - name: pets
+ description: Everything about your Pets
paths:
/pets:
get:
diff --git a/documents/forOpenAPISpecification/reference/divided_files_sample.zip b/documents/forOpenAPISpecification/reference/divided_files_sample.zip
index 6ffeea93..43903613 100644
Binary files a/documents/forOpenAPISpecification/reference/divided_files_sample.zip and b/documents/forOpenAPISpecification/reference/divided_files_sample.zip differ