RailsプロジェクトのためのSwagger UIセットアップ方法

明確でインタラクティブなAPIドキュメントを作成することは、保守可能でアクセスしやすいWebサービスを開発する上で重要です。Swagger UIは開発者向けの動的なドキュメントインターフェースとして機能し、Ruby on Railsプロジェクトに統合することで開発者の体験を大幅に向上させることができます。この投稿では、Grape API用のgrape-swaggerとRSpec APIドキュメント用のrswagという2つの人気のあるgemを使用してSwagger UIをセットアップするプロセスを分解して説明します。

パート1: Grape APIの場合

Grapeは、Rack上で動作するか、Railsなどの既存のWebアプリケーションフレームワークを補完するように設計された、Ruby用のRESTライクなAPIマイクロフレームワークです。Grape-swaggerは、Grape APIの自動生成されたドキュメントを提供します。

ステップ1: `grape-swagger`のインストール

grape-swaggerをGemfileに追加し、bundle installを実行してプロジェクトに追加します:

gem 'grape-swagger'

その後、以下を実行します:

bundle install

ステップ2: `grape-swagger`の設定

grape-swaggerのイニシャライザを設定します:

# config/initializers/swagger.rb

if defined?(Grape)
  GrapeSwaggerRails.options.url      = "/api/swagger_doc"
  GrapeSwaggerRails.options.app_name = "MyApp"
  GrapeSwaggerRails.options.app_url  = "/"
end

ステップ3: APIエンティティとドキュメントの定義

grape-swaggerがドキュメント化できるように、APIエンティティを定義する必要があります:

# app/api/entities/my_entity.rb

module API
  module Entities
    class MyEntity < Grape::Entity
      expose :id, documentation: { type: 'Integer', desc: 'ID of the entity' }
      # ... further code ...
    end
  end
end

ステップ4: Swaggerエンドポイントの追加

APIベースクラスにSwaggerドキュメントルートを追加し、Swagger JSONを提供できるようにします:

# app/api/base.rb

class API::Base < Grape::API
  add_swagger_documentation
end

ステップ5: Swaggerドキュメントの表示

http://localhost:3000/swaggerに移動してSwagger UIにアクセスできます。

パート2: RSpecを使用したRailsアプリの場合

rswagは、APIテストに基づいてSwagger互換のAPIドキュメントを自動生成するためにRSpecと統合します。

ステップ1: `rswag-specs`のインストール

Gemfileにrswag-specsを追加し、インストールします:

gem 'rswag-specs'

そして、以下を実行します:

bundle install

ステップ2: 設定とファイルの生成

RSwagジェネレーターを実行して、APIスペックの初期設定とディレクトリを作成します:

rails g rswag:install

ステップ3: Swagger DSLを使用したリクエストスペックの作成

スペックファイルを作成し、RSwagのDSLを使用してエンドポイントをテストし、ドキュメント化します:

# spec/integration/my_api_spec.rb

require 'swagger_helper'

describe 'My API' do
  path '/my_api/endpoint' do
    ...
    get 'Retrieves something' do
      produces 'application/json'
      response '200', 'successful' do
        schema type: :object,
               properties: {
                 id: { type: :integer }
               },
               required: ['id']

        # Your test code goes here
      end
    end
  end
end

ステップ4: RSwag UIを使用したAPIドキュメントへのアクセス

RSwagはSwagger UIを提供しており、http://localhost:3000/api-docsでアクセスできます。このUIは、作成したスペックを直接反映します。

代替案

RSpecを書きたくない場合や、GrapeAPIを使用していない場合は、最新の自動化ツールCordylineを試すことができます。

Auto Generate Swagger Doc

ドラッグ＆ドロップするだけで、コードを一行も書かずにSwagger Doc全体を生成します。