grape-swaggerでgrapeでつくったAPIのドキュメントを自動生成する

概要

grapeのドキュメントをSwagger UIで使える形で自動生成します。

Swagger UIとは

こんなんです。

APIとその説明を列挙し実際にパラメータを入力して叩くことができます。
超便利！

install

rails前提にしてますが、そうじゃなくてもいいかも。

  # Documentation
  gem 'grape-swagger'
  gem 'grape-swagger-ui'

add_swagger_documentationをソースに追加

api.rb

module API
  class Root < Grape::API
    mount API::Cats
    mount API::Dogs
    mount API::Pirates
    add_swagger_documentation
  end
end

確認する

bundle install
rails s 

アクセス
http://localhost:3000/api/swagger

もしv1とかでURLを切っていたら以下をフォームに入力してください。

http://localhost:3000/api/v1/swagger_doc.json

ドキュメントの書き方

こんな感じで書けるようです。詳しくはREADME.mdで。

api.rb

desc "Reserve a virgin in heaven", {
  :notes => <<-NOTE
    Virgins in heaven
    -----------------

    > A virgin doesn't come for free

    If you want to reserve a virgin in heaven, you have to do
    some crazy stuff on earth.

        def do_good
          puts 'help people'
        end

    * _Will go to Heaven:_ Probably
    * _Will go to Hell:_ Probably not
  NOTE
}

まとめ

ドキュメントだけでなく実行環境も手に入り一石二鳥ですね！