RailsのAPIモードでドキュメントを作成するならapipie-rails

目的
- やりたいこと
- 検討したこと
  - apiモードでインストールされるGemfile
実装手順
ドキュメントの確認
- 画面キャプチャ
関連本

目的

以前にdockerでraisのapiモードでアプリケーションを作成したので、その続きでapiのドキュメントツールを導入。 l-chika.hatenablog.com

やりたいこと

RailsのAPIモードでAPI仕様を実装と結びつけて作成したい
controllerのparameterに仕様、バリデーション実装からドキュメント・仕様が自動生成される
なるべくRailsそのものの機能を利用してAPIを実装したい(grape 等のgemを利用しない。良いgemなのだが学習コストやRailsのルールからはみ出す実装を求められることもあるので)

検討したこと

grape-swagger-rails の利用を検討したが、apiモードでは最低限のGemしかインストールされないでのassets系のgemがないので、swaggerのweb画面を表示する事ができない。追加でドキュメントのためだけにgemを追加するのも違和感があった。

apiモードでインストールされるGemfile

gem 'rails', '5.1.4'

gem 'mysql2', '>= 0.3.18', '< 0.5'
gem 'puma', '~> 3.7'

group :development, :test do
  gem 'byebug', platforms: %i[mri mingw x64_mingw]
end

group :development do
  gem 'listen', '>= 3.0.5', '< 3.2'
  gem 'spring'
  gem 'spring-watcher-listen', '~> 2.0.0'
end

gem 'tzinfo-data', platforms: %i[mingw mswin x64_mingw jruby]

そこで、 - 学習コストが低く - 実装をそのままドキュメント化できる - assets系の設定が不要な apipie-rails を採用。

github.com

実装手順

Gemfileの追加

maruku はドキュメントの記載に Markdown(Apipie::Markup::Markdown.new) を利用する場合に必要

gem 'apipie-rails'
gem 'maruku'

インストール

$ bundle install
$ rails g apipie:install

config/initializers/apipie.rb が生成
config/routes.rb が更新

`config/initializers/apipie.rb` の変更

Apipie.configure do |config|
  config.app_name = 'Hoge API'
  config.api_base_url = ''
  config.doc_base_url = '/doc'
  config.default_locale = 'ja'
  config.default_version = '1'
  config.languages = ['en', 'ja']
  config.markup = Apipie::Markup::Markdown.new
  config.api_controllers_matcher = Rails.root.join('app', 'controllers', '**', '*.rb')
  config.app_info['1'] = <<-EOS
    ## ほげAPI
    ---
    ## foo
    ### bar

    * a
    * b

        {
          "response": [
            {
              "a": "aa",
              "b": 111
            }
          ]
        }
  EOS
end