概要
RailsでオープンAPIを開発をするときに使うライブラリ選定メモです
オープンAPIとは？
サービスを低コストに拡大するポイントになります
メンテコストを下げるためのポイントと実現手段
| ポイント | 実現手段 |
|---|---|
| 1. APIクライアントを自動生成 | swagger-codegen |
| 2. ドキュメントを自動生成 | swagger-codegen, Swagger UI |
ぼくのかんがえた最強の構成
- swagger-blocks
- swagger-codegen
- Swagger UI
- commitee
モジュール一覧
swagger-blocks
https://github.com/fotinakis/swagger-blocks
star 425
swagger-codegen
Open API Specification -> APIクライアント
Open API Specification -> ドキュメント(HTML, confluence wiki)
Swagger UI
Open API Specification -> ドキュメント
https://swagger.io/tools/swagger-ui/
Web上でドキュメントを見られる。
grape
grape -> implementation
grape-swagger
grape -> Open API Specification
https://github.com/ruby-grape/grape-swagger
star 894
apivore
implementation + Open API Specification -> validity
テスト用
https://github.com/westfieldlabs/apivore
star 148
commitee
implementation + Open API Specification -> validity
rackミドルウェア用。動いているときに使えるっぽい
https://github.com/interagent/committee
star 286
議論
Grapeを使うべきか？
これを読んだ結果、grapeはやめたほうが良い気がした。
直感。
Grape-Swaggerを使うべきか？
grapeはやめたほうが良い。
Open API Specificationを記述したいなら、
それだけにフォーカスしたほうが良い。
実装とかと癒着しはじめると、変化に弱くなる。
-
https://inside.pixiv.blog/edvakf/2473
- Grape-Swagger、Swagger::Blocksの比較で参考にした
Oepn API Specificationを何で記述するべきか？
ymlか？swagger-blocksか？
選べないから、直感でswagger-blocksにする
https://qiita.com/kymmt90/items/439868c21abe077642fa
https://inside.pixiv.blog/edvakf/2473
http://tech.starttoday-tech.com/entry/swagger_yaml
追記
その後、Open API Specificationの記述を実際にやってみて、swagger-blocksよりも、Swagger Editorで手書きのほうがよさそうなことに気付く。
open api specification 3は対応していないライブラリが多いから、2を使う。
ぼくのかんがえた最強の構成v2
- open api specification 2
- 手書き Open API Specification yaml
- Swagger Editor
- swagger-codegen
- Swagger UI
- commitee
追記 (2019/05/18)
GraphQLもおすすめです。
かなり雑ですが、以下の記事はGraphQLを使った場合のライブラリ選定メモです。