今回の成果物
Swaglow
特長
特定のルールに基づいたディレクトリ階層から、SwaggerのYamlファイルを結合して出力する。
- SwaggerのYaml運用に最低限の秩序をもたらす
- フレームワークが生成したディレクトリに沿ってファイルを追加していくので、ファイル管理をルール化しやすい
- ディレクトリ階層や名前から
pathsやdefinitionsの定義を自動生成- 最終的なYamlがどう生成されるのか意識する必要は無い
- Yamlファイルを個別に管理していくことに集中できる
経緯
Swaggerで扱うYaml(or Json)は最終的には1つのファイルとして扱わないといけないが、何も考えずにそれに乗っかるとファイルが肥大化して管理しづらくなる。
そのためYamlを分割して結合するのが良く、npmにも既にそれを実現するライブラリも豊富にある。しかし、そのどれもが$refを使う方式で、これだとファイルをどの単位で分割するかのルールが無いので、もうちょっと仕組み的に縛りたかった。
導入
$ npm install -g swaglow
使い方
初期化
まずはプロジェクトのルートディレクトリでinitコマンドを実行
$ swaglow init -o [output path]
するとこのようなディレクトリが出力先に生成される
swaglow root // -oで指定したパスのルート
- swaglow.json // 専用のコンフィグファイル
- paths // APIのエンドポイントを管理するディレクトリ
- definitions // モデルを管理するディレクトリ
- parameters // APIリクエストで使う共通のパラメータを管理するディレクトリ
開発
簡単な例としてREADME.mdにある内容をリンク貼っとく
GitHub - chuross/swaglow: simple swagger framework
より実践的な例だと、このライブラリを使ってQiita API用のSwaggerを作るリポジトリを用意したのでそちらを確認してほしい
swagger-toolsなどを用いて出力したyamlをvalidateしたりiOS Clientにビルドする仕組みを入れてCIで回すようにしている
GitHub - chuross/qiita-swagger-yaml: swagger yaml file for Qiita
ビルド
$ swaglow build -o [output path]
出力先に結合されたSwagger Yamlファイルが生成される
ライセンス
MIT
あとがき
今回紹介したように手運用でSwaggerのYamlを生成するのは基本的にはオススメしない。
- 追従しないとサーバー側の実装と乖離する可能性がある(メンテコストの増加)
- Swagger Yaml職人が出る可能性がある(属人化)
- チーム全体で管理していく仕組み作りなどが必要になる
そういった意味では自社開発のAPIにリクエストを投げる場合であればメンテの効率を上げるためにサーバー側で書かれたコードから自動生成させるのが良いだろう。
では手運用は果たして意味が無いのかと言うと状況によってはそんなこともない。
例えばこのようなケースには使えると思われる
- プロジェクトがスタートした直後でサーバー側の準備ができていない場合
- モックサーバーとして活用する
- 本格的な運用はサーバー側ができたらそっちでやるのが良さそう
- 別会社・別チームのプロダクトなどそもそもSwaggerの連携が難しい場合
このような感じでケース・バイ・ケースだと思うので、もし何らかの理由で手運用の管理が必要になった場合はこのフレームワークを使うと良いかもしれない。