OpenAPIのYAMLをVSCodeで分割管理する #VSCode

本記事はOpenAPI3.0を使用しています

OpenAPIのつらいところ

APIの数が増えていくと、数千行、Exampleまで丁寧に書いている、あっという間に数万行に達してしまいます。

開発環境

VSCodeに必要な拡張を入れましょう

VSCodeの拡張

extensions.json

{
    "recommendations": [
        // OpenAPI (Swagger) Editor
        "42crunch.vscode-openapi",
        // OpenApi Designer
        "philosowaffle.openapi-designer",
        // Prettier
        "esbenp.prettier-vscode"
    ]
}

OpenAPI (Swagger) Editor

ID: 42crunch.vscode-openapi

インストールしておくと$refの参照先YAMLにコードジャンプできます。 APIの数が増えるとファイルが数十・数百と増えていくのコードジャンプできるのは非常に便利です

OpenApi Designer

ID: philosowaffle.openapi-designer

プレビュー表示する拡張
分割したopenapi.ymlでもプレビュー表示してくれるのが特長です
yamlファイルを編集して保存すると、プレビューも自動更新されます(ホットリロード)
プレビュー画面はコマンドパレットから起動 ctrl-shft-p > OpenApi Designer: Preview

Prettier

ID: esbenp.prettier-vscode

YAMLのフォーマッタ(https://prettier.io/)

ツール

YAML結合

分割されたままだと他のツールを使うときに不便なのでswagger-cliを用いて結合しています。

swagger-cli bundle -r openapi/openapi.yml -o build/openapi.json

出力形式はyamlとjsonどちらも対応しています

静的HTML生成 ReDoc

結合したopenapi.jsonから静的なHTMLを生成するツールです
HTMLを作成するツールはいくつかあるのですが、ReDocが一番キレイで見やすいと思います

- 成果物が単一のHTMLファイルなので共有するのも簡単です。

redoc-cli bundle build/openapi.json --options.menuToggle --options.pathInMiddlePanel  -o build/redoc-static.html

自分はオプションで以下の2つをONにしています

--options.menuToggle: 左のmenuをトグルできるようにする
--options.pathInMiddlePanel: 中央にAPIのエンドポイントパスを表示する

Swagger UI

ReDocではなくSwaggerUIのほうが見やすいという方は、dockerを使用してローカルにSwaggerUIをホストしましょう

docker run -p 8081:8080 -v $(pwd)/openapi:/usr/share/nginx/html/openapi -e API_URL=openapi/openapi.yml swaggerapi/swagger-ui

Mockサーバー Prism

ドキュメント通りにAPIのMockサーバーを建てることができます。戻り値はexampleを返します。

prism mock openapi/openapi.yml

ファイル分割とディレクトリ構造

横展開しやすいことを考えて末にたどり着いたディレクトリ構造です。

再利用はあまり意識しない
自分が編集しているAPIにのみ集中できるようにする(視界に他のAPIが入らないようにする)
分割のデメリットはコードジャンプで補う
API追加・編集作業をルーチン化できるように分ける
ディレクトリ名はキャメルケース、ファイル名はケバブケースに統一する
openapi.ymlはエンドポイント俯瞰のためにシンプルに保つ

実例

./
 +- openapi
    |- openapi.yml
    +- components       分割したYAMLファイルの置き場
         |- errors        エラー系の戻り値の構造とExample
         |- examples      正常系の戻り値の例
         |- parameters    APIのパラメタ
         |    |- header     headerのパラメタ
         |    |- path       pathパラメタ
         |    +- query      queryStringパラメタ
         |
         |- paths         openapi.ymlのpaths
         |- requestBody   リクエストボディ(POST/PUTのBody)
         +- schemas       各APIのスキーマ

openapiディレクトリに全ファイルをまとめておくとdockerでmountするときに便利です。
openapi.ymlはエンドポイントの一覧になります。エンドポイントを俯瞰しやすくなります。
components内にドキュメントの詳細を書いていきます。
components/pathsには各エンドポイントのGET/POST/PUT/DELETEなどの処理の記述をしていきます
components/schemaには戻り値の構造を記述、
`components/exampleには戻り値の例を定義します。
components/errors, components/requestBody, components/parametersは再利用を意識して管理しておきます
components/parametersはheader, path, queryに分けています。これは同じパラメタ名がpathとquery両方に存在するケースがあったためです。

これは一例なので状況に応じて構造を変えましょう。どのエンドポイントが、どのコンポーネントを使っているかわかりやすくすることが重要です。

まとめ

OpenAPIはすぐに肥大化するのでファイル分割しよう
OpenAPIを分割してもVSCodeの拡張を活用しよう
分割したyamlでは他のツールと連携しづらいので結合できるようしよう
ReDocなどを使ってopenapi.jsonからHTMLを作成し共有しよう
保守しやすくするためにディレクトリ構造を工夫しよう