APIのドキュメントを生成するGem「autodoc」の使い方

プログラミング

こんにちは！kossyです！





今回はAPIのドキュメントを自動で生成するGemである「autodoc」の使い方について、
ブログに残してみたいと思います。



github.com



環境
Ruby 2.6.6
Rails 6.0.3
MacOS Catalina
autodoc 0.7.5



導入

導入は至って簡単です。

# Gemfile

group :test do
  gem 'autodoc'
end

# terminal

$ bundle install

任意のRequestSpecにautodoc: trueを追記します。

# spec/requests/recipes_spec.rb
describe "Recipes" do
  describe "POST /recipes", autodoc: true do
    it "creates a new recipe" do
      post "/recipes", name: "alice", type: 1
      response.status.should == 201
    end
  end
end

この状態で、terminalでautodoc=1 bundle exec rspec spec/requestsを実行します。

$ autodoc=1 bundle exec rspec spec/requests

このコマンドを実行することで、ルートディレクトリにdoc/recipes.mdが作成されます。


mdファイル生成先を変更したい場合

デフォルトではdoc/配下に出力されるドキュメントですが、生成先を変更することができます。

  # spec/rails_helper.rb
  
RSpec.configure do |config|
  # 省略

  # for Autodoc
  Autodoc.configuration.path = 'docs/api'

spec/rails_helper.rbでAutodoc.configuration.path = 'docs/api'と指定することで、ルートディレクトリのdocs配下のapiディレクトリにmdファイルが生成されるようになります。


ドキュメントの出力形式を変更したい

デフォルトではHttpRequestのBody部が出力されないので、Request Bodyも出力されるようにerbファイルを作成します。

# spec/autodoc/templates/document.md.erb

## <%= title %>
<%= description %>
<%= parameters_section %>
#### Request
```
<%= method %> <%= request.path %><%= request_query %>
```
<% if request_body_section.present? %>
<% if request_body_section.strip == 'multipart/form-data' %>
```
<%= request.env['rack.request.form_hash'].inspect %>
```
<% else %>
```json
{<% URI.decode_www_form(request_body_section.strip).each do |arr| %>
  <%= arr[0] %>: "<%= arr[1] %>",
<% end %>}
```
<% end %>
<% end %>
#### Response
```
<%= response_http_version %> <%= response.status %>
<%= response_header %><%= response_body_section %>
```

あとは spec/rails_helper.rb でドキュメント生成時に利用するerbファイルを指定してあげるだけです。

  # spec/rails_helper.rb
  
RSpec.configure do |config|
  # 省略

  # for Autodoc
  Autodoc.configuration.path = 'docs/api'

  # 追加
  Autodoc.configuration.template = File.read(File.expand_path('../autodoc/templates/document.md.erb', __FILE__))

これで出力されるmdファイルは以下のようになります。

## POST /supervisor/ips
IPアドレス制限を設定できること.

#### Request
```
POST /supervisor/ips
```


```json
{
  content: "127.0.0.1",
}
```


#### Response
```
HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 99
Content-Type: application/json; charset=utf-8
ETag: W/"545ba7565213c5da92a1067d90ba1f71"
Referrer-Policy: strict-origin-when-cross-origin
Vary: Origin
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Frame-Options: SAMEORIGIN
X-Permitted-Cross-Domain-Policies: none
X-Request-Id: 8cc8356f-9a61-4ed6-9184-8fc26c11db76
X-Runtime: 0.034126
X-XSS-Protection: 1; mode=block
access-token: TNJu5tShW-QUuezNUPXcEQ
client: QyIMw5NVQ-xj0cn4ePV9zg
expiry: 1618410677
token-type: Bearer
uid: carol_kulas@example.net
{
  "content_str": "127.0.0.1",
  "setted_at": "2021-03-31T23:31:17.000+09:00",
  "full_name": "吉田 高志"
}
```
## PATCH /supervisor/ips/:uuid
IPアドレス制限を更新できること.

#### Request

```
PATCH /supervisor/ips/eb926dcc-c949-46e8-88ef-38ba1c3aed15
```


```json
{
  content: "127.0.0.2",
}
```


#### Response
```
HTTP/1.1 200
Cache-Control: max-age=0, private, must-revalidate
Content-Length: 99
Content-Type: application/json; charset=utf-8
ETag: W/"a21894b45232cf04cdc8f632057cb475"
Referrer-Policy: strict-origin-when-cross-origin
Vary: Origin
X-Content-Type-Options: nosniff
X-Download-Options: noopen
X-Frame-Options: SAMEORIGIN
X-Permitted-Cross-Domain-Policies: none
X-Request-Id: 122913ac-1a7b-49bf-8400-ca9acbb1c1d9
X-Runtime: 0.056721
X-XSS-Protection: 1; mode=block
access-token: SkYvm3g9Bs2s9uq6v7s3Dw
client: uLPcyFrr1LRKpi2M_tNLBQ
expiry: 1618410677
token-type: Bearer
uid: ursula@example.org

{
  "content_str": "127.0.0.2",
  "setted_at": "2021-03-31T23:31:17.000+09:00",
  "full_name": "吉田 高志"
}
```

導入も簡単でカスタマイズも容易なのでおすすめです。