おいちゃんと呼ばれています

ウェブ技術や日々考えたことなどを綴っていきます

Rails でつくる API のドキュメントを自動生成してくれる autodoc がすごい

Rails

最近 Rails で API をつくりはじめたのですが、ドキュメントをどうしようかなと悩んでいまして。なにかイイ感じに自動生成してくれるツールはないものかと探していたら、@ さんと id:antipop さんがまさにズバリのものを教えてくれました。

先日ふわっとリリースされた模様。

これヤバい。ので、どのくらいヤバいかを共有しようと思います。

Step 1. テスト内に autodoc: true と書く

例えば下記のような感じで、ドキュメントを生成したい対象のテストに autodoc: true と書きます。

# spec/requests/videos_spec.rb
require 'spec_helper'

describe '動画に関する API' do

  describe "GET /api/videos.json" do
    before do
      @video1 = FactoryGirl.create(:video, title: 'すぐにまたがる家庭教師')
      @video2 = FactoryGirl.create(:video, title: '夫のために身体を差し出す人妻')
      get "/api/videos.json"
    end

    it '200 OK が返ってくる' do
      expect(response).to be_success
      expect(response.status).to eq(200)
    end

    it '動画一覧を取得できる', autodoc: true do
      expect(response.body).to match(/すぐにまたがる家庭教師/)
      expect(response.body).to match(/夫のために身体を差し出す人妻/)
    end

  end
end

Step 2. AUTODOC=1 を付けてテストを実行

AUTODOC=1 を付けてテストを実行します。

$ AUTODOC=1 bundle exec rspec/spec/requests/videos_spec.rb

Step 3. 生成されたドキュメントを確認する

うまくいっていれば、doc/videos.md が生成されているはずです。GitHub で見ると下記のような感じで、あんまり手抜き感がない（！）

f:id:inouetakuya:20131020130923p:plain

API document generated by autodoc(https://github.com/r7kamura/autodoc)

リポジトリを GitHub Enterprise で管理しているので、doc/ の URL を API を叩く開発者に向けて IRC に貼って、

doc/ 内が随時更新されていくからよろしくね☆

と伝えれば、もうそれで終了という。。

必要十分な要件が満たされていて、とてもイイ感じ。いや、もう、ほんっと助かりましたわー！！

ドキュメントのテンプレートはカスタマイズできる

あと、生成されるドキュメントのテンプレートはカスタマイズできるようです。僕自身は、標準設定で生成されるドキュメントで必要十分だと思ったのでカスタマイズしなかったのですが。詳しくは公式ドキュメントを参照してください。

ではでは。