2022年5月27日金曜日

OpenAPI or Swagger ファイルを分割して管理する方法

概要
環境
swagger-cli のインストール
分割前のファイル
schemas/pet.yaml の作成
parameters の分割
ファイルを結合して動作確認
最後に
参考サイト

概要

今回は 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 ごとにもファイルを作成すると管理しやすそうです

参考サイト

https://davidgarcia.dev/posts/how-to-split-open-api-spec-into-multiple-files/

hawksnowlog