はじめに

Railsアプリケーションの開発において、APIのテストとドキュメント化は重要な要素です。

RSpecはテストフレームワークとして広く利用されており、SwaggerはAPIの設計とドキュメント化を支援します。これらを統合するrswagを使うことで、テストとドキュメントを一貫して管理し、信頼性の高いAPIを提供することができます。

本記事では、RSpec、Swagger、rswagを使用してRailsアプリケーションのAPIをテストおよびドキュメント化する方法について説明します。

概要

RSpec、Swagger、rswagそれぞれの概要について簡単に紹介します。

RSpec

RSpecは、RubyのためのBDD（Behavior-Driven Development）ツールです。Railsアプリケーションにおけるテストフレームワークとして広く使われています。RSpecを使用することで、アプリケーションの期待される動作を明確にし、その動作が維持されることを保証するテストを書けます。

Swagger

Swaggerは、APIの設計、構築、ドキュメント化を簡単にするためのツールセットです。Swaggerは、OpenAPI Specification（以前はSwagger Specificationとして知られていた）に基づいています。この仕様は、RESTful APIを記述するための標準的なフォーマットを提供します。

rswag

rswagは、RSpecとSwaggerを統合し、RailsアプリケーションのAPIドキュメントとテストを同時に管理できるツールです。rswagを使用すると、RSpecテストから直接Swaggerドキュメントを生成できます。

APIのテストとドキュメント化

Gemのインストール

まず、RSpec、Swagger、rswagをインストールします。Gemfileに以下を追加し、bundle installを実行します。

Gemfile

group :development, :test do
  gem 'rspec-rails'
  gem 'rswag'
end

その後、RSpecとrswagのセットアップを行います。

% rails generate rspec:install
% rails generate rswag:install

Swaggerの設定

Swaggerの設定ファイルはspec/swagger_helper.rbにあります。ここで、Swaggerの設定を行います。

spec/swagger_helper.rb

RSpec.configure do |config|
  config.swagger_root = Rails.root.to_s + '/swagger'

  config.swagger_docs = {
    'v1/swagger.yaml' => {
      openapi: '3.0.1',
      info: {
        title: 'API V1',
        version: 'v1'
      },
      paths: {},
      servers: [
        {
          url: 'http://localhost:3000',
          variables: {
            defaultHost: {
              default: 'localhost:3000'
            }
          }
        }
      ]
    }
  }

  config.swagger_format = :yaml
end

APIドキュメントとテストの作成

次に、APIのドキュメントとテストを作成します。例として、articlesエンドポイントを使用します。

テストとドキュメントの作成

spec/integration/articles_spec.rbにテストとドキュメントを記述します。

spec/integration/articles_spec.rb

require 'swagger_helper'

RSpec.describe 'Articles API', type: :request do
  path '/articles' do
    get 'Retrieves all articles' do
      tags 'Articles'
      produces 'application/json'

      response '200', 'articles found' do
        schema type: :array, items: { type: :object, properties: { id: { type: :integer }, title: { type: :string }, content: { type: :string } } }

        before do
          create(:article, title: 'Sample Article', content: 'This is a sample article.')
        end

        run_test!
      end
    end

    post 'Creates an article' do
      tags 'Articles'
      consumes 'application/json'
      parameter name: :article, in: :body, schema: {
        type: :object,
        properties: {
          title: { type: :string },
          content: { type: :string }
        },
        required: ['title', 'content']
      }

      response '201', 'article created' do
        let(:article) { { title: 'New Article', content: 'This is a new article.' } }
        run_test!
      end

      response '422', 'invalid request' do
        let(:article) { { title: 'New Article' } }
        run_test!
      end
    end
  end
end

Swaggerドキュメントの生成と表示

Swaggerドキュメントを生成します。

% bundle exec rake rswag:specs:swaggerize

次に、生成されたSwaggerドキュメントを表示するために、ルーティングを設定します。

config/routes.rb

Rails.application.routes.draw do
  resources :articles

  # Swagger UI
  mount Rswag::Ui::Engine => '/api-docs'
  mount Rswag::Api::Engine => '/api-docs'
end