背景#

• 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をインストールします。

$ bundle

swaggerの初期設定ファイルを作成します。
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.json
  • https://postcode.teraren.com/apidocs/api-docs.json
• public/apidocs/postcodes.json
  • https://postcode.teraren.com/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は活発そうです。