概要
今回は swagger-cli を使った方法を紹介します
どんなツールを使うにしろ最終的には分割した YAML ファイルを結合する処理が必要になります
環境
- macOS 11.6.6
- swagger-cli
swagger-cli のインストール
- npm install -g @apidevtools/swagger-cli
分割前のファイル
共通部分などを各パートごとに分割します
以下は分割前のファイルになります
- vim openapi.yaml
openapi: 3.0.0
info:
title: split test
version: 1.0.0
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
format: int32
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
type: "array"
items:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
/pets/{petId}:
get:
summary: Info for a specific pet
operationId: showPetById
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:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
schemas/pet.yaml の作成
レスポンスで使用するオブジェクトが共通なので分割します
schemas/pet.yaml として切り出します
- vim schemas/pet.yaml
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
あとはこれを ref で参照します
- vim openapi.yaml
openapi: 3.0.0
info:
title: split test
version: 1.0.0
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
format: int32
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
type: "array"
items:
$ref: "./schemas/pet.yaml"
/pets/{petId}:
get:
summary: Info for a specific pet
operationId: showPetById
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: "./schemas/pet.yaml"
parameters の分割
今度は少し応用テクニックを紹介します
parameters の役割で分割して管理しやすくしてみます
まず定義した parameters をすべて読み込むファイルを作成します
- vim parameters/_index.yaml
petId:
$ref: './petId.yaml'
limit:
$ref: './limit.yaml'
パラメータはそれぞれ個別ファイルに定義します
- vim parameters/petId.yaml
name: petId
in: path
required: true
description: The id of the pet to retrieve
schema:
type: string
- vim parameters/limit.yaml
name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
format: int32
あとはそれぞれのファイルをメインのファイルから参照するように変更します
- vim openapi.yaml
openapi: 3.0.0
info:
title: split test
version: 1.0.0
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- $ref: "./parameters/limit.yaml"
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
type: "array"
items:
$ref: "./schemas/pet.yaml"
/pets/{petId}:
get:
summary: Info for a specific pet
operationId: showPetById
tags:
- pets
parameters:
- $ref: "./parameters/petId.yaml"
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "./schemas/pet.yaml"
components:
parameters:
$ref: "./parameters/_index.yaml"
ファイルを結合して動作確認
ファイルの結合には swagger-cli を使います
-
swagger-cli bundle openapi.yaml --outfile _build/openapi.yaml --type yaml
これで _build/openapi.yaml が出来上がるので swagger ui などで確認するとちゃんと分割前と同じ情報が確認できると思います
できあたがったファイルを見ると ref 先をファイルに埋め込んでパスで無理やり参照しています
また今回の分割後のファイル構成は以下のようになっています
% tree .
.
├── _build
│ └── openapi.yaml
├── openapi.yaml
├── parameters
│ ├── _index.yaml
│ ├── limit.yaml
│ └── petId.yaml
└── schemas
└── pet.yaml
3 directories, 6 file
最後に
基本は分割して ref で参照して結合するだけです
分割の仕方はいろいろありますが基本的には共通部分や役割ごとに分割すると良いと思います
参考サイトにあるように parameters, responses, schemas で分割してあとは paths ごとにもファイルを作成すると管理しやすそうです
