reona.dev

yamlinc について


はじめに

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

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

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

javanile / yamlinc

yamlinc について

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

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

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

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

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

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

詰まった点

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

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

ログを確認すると、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 ってなによ。って感じだったけど、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 も非常に良いのでおすすめ。