こんにちは！RailsでのAPI開発、日々楽しんでいますか？
「昔勢いで作ったRailsのAPI、ドキュメントなんて影も形もない……」
「フロントエンドのメンバーから『エンドポイントの仕様書どこですか？』って聞かれるたびに冷や汗が出る……」
「かといって、今更手動でSwaggerのYAML書くなんて絶対ムリ！」
そんな絶望的な状況に陥っているあなたへ。安心してください、救世主はちゃんといます。今回は、既存のRailsアプリに `rswag` というGemを導入し、「統合テストを書くだけで、最高にイケてるOpenAPI（Swagger）ドキュメントが勝手に生えてくる」という魔法のような手法を伝授します。
これをマスターすれば、ドキュメントの書き忘れや「コードとドキュメントの乖離」という永遠の呪縛から解放されますよ。さあ、一緒にレガシーAPIを現代に蘇らせましょう！
—
1. なぜ「rswag」なのか？（ツールの役割と設計思想）
世の中には、コードのコメントからSwaggerを生成するツール（`swated` や `apidoc` など）もありますが、私は声を大にして言いたい。「APIのドキュメントは、テストと一緒に生きるべきだ」と。
`rswag` の思想はシンプルです。「RSpecによる統合テスト（リクエストスペック）」を書き、その中で「このリクエストを送ったら、こういうレスポンスが返るべきだ」というスキーマ（型や構造）の定義を記述します。
すると、テストが成功した瞬間に、その正当性が保証されたOpenAPI定義（JSON/YAML）が自動生成されるのです。
つまり、「動くテスト＝最新のドキュメント」という最強の自動化パイプラインが完成します。ドキュメントの嘘が物理的に存在できなくなる、これが `rswag` を選ぶべき最大の理由です。
—
2. 導入ステップ：最小構成で環境を整える
それでは、既存のRailsアプリに `rswag` を組み込んでいきましょう。前提として、RSpecがすでに導入されているプロジェクトを想定して進めます。
Step 1: Gemのインストール
`Gemfile` に以下の3つのGemを追加します。`rswag-specs` はテスト用、`rswag-ui` はブラウザでドキュメントを表示するためのものです。
Gemfile
group :development, :test do
gem ‘rspec-rails’
# rswagファミリーの追加
gem ‘rswag-api’
gem ‘rswag-specs’
gem ‘rswag-ui’
end
ターミナルを開き、お馴染みのコマンドを実行します。
bundle install
Step 2: インストールジェネレータの実行
次に、rswagの設定ファイルやディレクトリ構造を一気に生成するジェネレータを実行します。
rails g rswag:install
これにより、以下の変更・作成が行われます：
1. `config/initializers/rswag_api.rb` と `rswag_ui.rb` が生成される。
2. RSpecの設定（`spec/rails_helper.rb` など）にフックが追加される。
—
3. HelloWorld的実践：最初のAPIドキュメントを生やす
今回は題材として、既存の `Api::V1::ArticlesController`（記事一覧・詳細を返すAPI）があると仮定しましょう。このAPIの「記事一覧取得 (`GET /api/v1/articles`)」に対してドキュメントを生やします。
Step 1: スキーマ定義付きのRSpecを書く
`rswag` では、RSpecの構文を拡張してOpenAPIのメタデータを記述します。
`spec/requests/api/v1/articles_spec.rb` というファイルを作成し、以下のように記述してください。
spec/requests/api/v1/articles_spec.rb
require ‘swagger_rails’
RSpec.describe ‘Api::V1::Articles’, type: :request do
path ‘/api/v1/articles’ do
get ‘記事一覧を取得する’ do
tags ‘Articles’
produces ‘application/json’
response ‘200’, ‘成功：記事の配列を返す’ do
# レスポンスのスキーマ（構造）をここで定義する
schema type: :array,
items: {
type: :object,
properties: {
id: { type: :integer },
title: { type: :string },
body: { type: :string },
created_at: { type: :string, format: :’date-time’ }
},
required: [ ‘id’, ‘title’, ‘body’ ]
}
# 実際にテストデータを突っ込んでリクエストを飛ばす
let!(:articles) { create_list(:article, 3) } # FactoryBotの例
run_test! do |response|
# ここに通常のRSpecの検証アサーションを書くことも可能
data = JSON.parse(response.body)
expect(data.length).to eq(3)
end
end
end
end
end
先輩のワンポイントアドバイス:
> ここで定義した `schema` が、そのままOpenAPIの仕様書に反映されます。「型」や「必須プロパティ (`required`)」を厳格に書いておくことで、フロントエンドエンジニアとの型ズレを防ぐ強固な契約（Contract）になります。
Step 2: テストを実行してドキュメントを「生成」する
さあ、魔法の発動です。以下のコマンドを実行してください。
rails rswag:specs:swaggerize
おっと、何が起きたかわかりましたか？
内部でRSpecが実行され、テストがパスすると同時に、プロジェクトのルート付近（通常は `swagger/v1/swagger.yaml`）に、ピカピカのOpenAPI定義ファイルが自動生成されたはずです！
—
4. ブラウザで美しく確認する（Swagger UIの起動）
ドキュメントのファイルができたら、人間が読みやすいようにリッチなUIで確認しましょう。
Railsサーバーを起動します。
rails s
ブラウザで以下のURLにアクセスしてみてください：
`http://localhost:3000/api-docs`
どうですか？あの雑然としていたレガシーAPIが、美しく整理されたSwagger UI（インタラクティブなAPIドキュメント）として蘇ったはずです。画面上で「Try it out」ボタンを押して、実際にAPIを叩いて動作確認することも可能です。
—
5. 現場で役立つ！CI連携によるメンテナンスの自動化
「ドキュメント生成を手動でやるのを忘れて、また古い仕様書が放置される……」
そんな未来を防ぐために、GitHub ActionsなどのCI環境にこのプロセスを組み込みましょう。
PR（プルリクエスト）が作成されたタイミングで、「テストが通るか」と「Swagger定義に差分がないか（自動生成漏れがないか）」を機械的にチェックさせます。
.github/workflows/api_docs.yml のサンプル
name: API Docs CI
on:
pull_request:
branches: [ main ]
jobs:
swagger_check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: ‘3.2’
bundler-cache: true
- name: Run Rswag & Check diff
run: |
bundle exec rails rswag:specs:swaggerize
# 生成されたswagger.yamlに差分がないか（git add/commit忘れてないか）チェック
git diff –exit-code swagger/v1/swagger.yaml
このCIを入れておけば、「仕様を変更したのに、rswagのタスクを実行してyamlを更新し忘れた！」というミスを完全にブロックできます。常にコードとドキュメントの同期が保たれる、最高にクリーンな開発フローの出来上がりです。
—
まとめ
今回は `rswag` を使って、既存のRailsアプリに統合テストファーストでOpenAPIドキュメントを生やす手法を解説しました。
1. RSpecを書く（スキーマ定義も含める）
2. `rails rswag:specs:swaggerize` を叩く（ドキュメント自動生成）
3. CIでメンテナンスを自動化する
この3ステップを回すだけで、レガシーだったAPI群が、フロントエンドから愛される「モダンで親切なAPI」へと生まれ変わります。
毎日の作業が劇的に楽になり、チーム全体の生産性が跳ね上がるのをぜひ実感してください。あなたのAPI開発ライフがより快適になることを応援しています！