Railsによるメンテコストの低いオープンAPI開発

概要

RailsでオープンAPIを開発をするときに使うライブラリ選定メモです

オープンAPIとは？

http://garapon.hatenablog.com/entry/2016/10/25/_%E3%82%AA%E3%83%BC%E3%83%97%E3%83%B3API%E3%81%A8Open_API%E3%81%A8%E3%81%A8Web_API%E3%81%A8REST_API%E3%81%AE%E9%81%95%E3%81%84%E3%80%82
の定義によります。

サービスを低コストに拡大するポイントになります

メンテコストを下げるためのポイントと実現手段

ぼくのかんがえた最強の構成

• 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を使った場合のライブラリ選定メモです。

Rails + Nuxt + GraphQLでSSR対応のSPAを作る場合の俺的ベストプラクティス