Swagger/OpenAPIを整理する
募集中
2021-08-24 に投稿しました
Ruby
やりたいこと
- https://github.com/willnet/committee-rails にOpenAPI/Swaggerを渡せばRequestSpecでレスポンスがスキーマに合っているか確認できるので使いたい
- OpenAPI (Swagger v3) を使いたい。OpenAPIを使うことによってnullable属性などいくつかスキーマが表現しやすくするように改良が入っておりhttps://github.com/willnet/committee-rails でも対応できている
- OpenAPIのスキーマにレスポンスを加えたい。ただ全APIを一気にやると時間がかかるので新規追加や改修が入るAPIを都度追加したらいいではと思う
現状
以下、把握していること。相違あればご教示ください。
- Swagger (v2) をSwaggerUIの表示に使っている (全環境)
- SwaggerのスキーマをSwaggerBlocks gemを使って生成している
変更したいところ
- SwaggerBlocksはOpenAPIに対応していないためSwaggerBlocksをやめてYAMLで記述したい。YAMLで書いたほうが標準的かつ簡潔で済む。SwaggerBlocksはここ4年近く更新がない。
- SwaggerUI gemをやめたい。OpenAPIに対応していないので仕方なく、という理由。Web画面が必要ならSwaggerUI (gemじゃないほう) など (前職でhttps://github.com/Redocly/redoc というUIを使っていた) を導入すれば表示できる。ただRailsではなくなるので本番環境でも使いたい場合は別途仕組みが必要。個人的に全環境で見る要件がわかっていないのだが、もし本番環境で見る必要がなければローカルでhtmlを生成するほうが一番楽そう。