yamlinc について

はじめに

以前 OpenAPI 仕様の API リファレンスについて記事を書いた。

OpenAPI (Swagger) で API リファレンス作成

その後、次のライブラリによるリファレンスの管理を開始したので紹介する。

javanile / yamlinc

yamlinc について

yamlinc を使うと、コンポーネント化した OpenAPI のファイルを 1 つにまとめてくれる。 基本的な使い方は README を参照。

これまでの管理と違う点は大きく 2 つ

• $include という特殊なタグを使用してコンポーネントを読み込む。公式の $ref を置き換えるイメージで OK
• $ yamlinc my_swagger_doc.yml コマンドによってコンパイルされ、1 つにまとまった my_swagger_doc.inc.yml ファイルができる

Swagger3.0 以前はコンポーネント化できず、1 つのファイルでリファレンス管理が行なわれていたが、yamlinc を使えばコンポーネントとしての管理はもちろん、コンパイルによってすべてのパスとその詳細が記されたファイルが自動生成される。

yamlinc という名前だが、-o オプションでファイル名を指定すれば json フォーマットのファイル生成も可能。

Docker で開発している場合、 --watch オプションで監視してくれるので、変更したタイミングでコンパイルしてくれる。

--strict オプションで構文エラーもログで指摘してくれる。

詰まった点

Rails プロジェクトで vendor/bundle がある場合、

• コンパイルにかなりの時間がかかる
  • 終わるまで 7 分かかり、その間 rails コマンドが叩けない。異常。
• 変更がコンパイル後のファイルに反映されていない

ということがあり、解決に時間がかかった。

ログを確認すると、vendor/bundle 配下の OpenAPI コンポーネントも読み取ってコンパイルしていたので、一度 vendor/bundle を削除し docker-compose を起動し直したが解決せず。

再び vendor/bundle のコンポーネントがコンパイルされていたので、 .bundle/config で BUNDLE_PARH = 'vendor/bundle' の指定を削除。docker-compose down docker-compose up するも、効果なし。

一度 docker system prune --volumes で不要なコンテナやボリュームを削除し、再度 docker-compose を立ち上げると成功した。 不要なデータが yamlinc コンテナの volume に永続化されたままだった。

• vendor/bundle を削除
  • BUNDLE_PARH の指定が vendor/bundle の場合は削除
• docker の volumes を削除

正直 vendor/bundle ってなによ。って感じだったけど、Rubyist ならおなじみの伊藤淳一さんが丁寧に解説してくれてた。

bundle install 時に--path vendor/bundle を付ける必要性は本当にあるのか、もう一度よく考えてみよう

この記事で思い出したけど、

[Vim] 定義元ジャンプを filetype で使い分ける

上の記事で vendor/bundle を用意することで gem コードへのタグジャンプを可能にしてたんだった。

gem に関するタグはすでに生成されてはいるけど念の為 BUNDLE_PARH = 'vendor/bundle' を設定して bundle install 、 docker-compose up してみると問題なかったので、とりあえずこのまま。

さいごに

OpenAPI によるリファレンス管理は学習コストがそれなりにあって、チーム開発の場合は時間がかかりがち。

yamlinc を導入すればコンポーネント分けできて管理は楽だし、設定すれば構文チェックや自動コンパイルしてくれるので API ドキュメントの保守運用がめっちゃ楽になる。

例えばこのドキュメントを元に openapi-generator だったりでクライアント API 作成時のモデルとなるコードの自動生成を行なったりすれば確実で DX も非常に良いのでおすすめ。