背景
- Web API Advent Calendar 12月3日分
- @takurosさんの12月2日のSwaggerとは何か？ を前提としています。
概要
- swagger-docs を使ってRailsのREST APIをswaggerで表示出来るようにします。
- 郵便番号検索APIのAPIを表現してみます。
手順
Gemfileにswagger-docsを追加します。- しかしながら、masterブランチにバグがあり、pathにスラッシュが付かないので、forkされたgemを使います。
gemをインストールします。
$ bundleswaggerの初期設定ファイルを作成します。
initializerをconfig/initializers/swagger_docs.rbに作成して、以下のようにAPIサーバの基本情報を書いておきます。
該当するControllerに、API仕様を追記します。
今回は、5行目から40行目を追記しました。
swaggerの定義ファイルをJSON形式で出力します。
以下のrakeタスクが、controllerを全て読んで、先ほど書いた設定をパースしてくれます。
（もし、deploy時に生成したい場合は以下のrakeタスクをcapistranoなどで実行するようにしておきます。）
% rake swagger:docs上記のコマンドが実行されることにより、以下のファイルが出力されます。
public/apidocs/api-docs.jsonpublic/apidocs/postcodes.json
デモ
- http://petstore.swagger.io/ の上部にあるテキストボックスに以下のSwaggerの設定ファイルであるJSONを入力すると、ドキュメント表示とREST APIをテスト出来ます。
- https://postcode.teraren.com/apidocs/postcodes.json
スクリーンショット
まとめ
- https://postcode.teraren.com/のAPIをswaggerで表現して、ローカルでテストしてみました。
- swagger-docsの最終更新日は1年以上前で、重要な不具合があるので利用はオススメ出来ません。
- grape-swaggerは活発そうです。
Comments