🔔 本の下書きプレビューをシェアできるようになりました

Open3ヶ月前にコメント追加5

rswagについて

 What is "rswag" ?rswagとは、RSpecをベースとしたOpenAPI(Swagger)と組み合わせたテスティングライブラリ

https://github.com/rswag/rswag
テストだけじゃなくて、以下の機能も提供している。
OpenAPIのYAML(JSON)ファイル自動生成
RSpecに記述した内容からドキュメントファイルを自動生成できる
APIドキュメントのUI提供
Railsのルーティングに追加してブラウザから閲覧が可能

Getting Started

これは公式ドキュメント通りに実施するだけ。

# Gemfileに以下の内容を追加
group :development, :test do
  gem 'rswag'
end

上記追加後、コマンド実行

bundle install

# 以下のコマンドで必要な設定ファイルを追加してくれる
rails g rswag:install

UI機能が不要であれば、必要なライブラリだけ入れることも可能らしいが、今回は全部入りで検証。

RSpec実装

RSpecで以下のように実装することで、OpenAPIの定義を記載できる

spec/requests/todos_spec.rb
# 以下のモジュールを読み込むことでrswagの定義を使えるようになる
require 'swagger_helper

describe "GET /index" do
  # pathの定義でAPIのエンドポイントを指定
  path "/api/v1/todos" do
     # HTTPのメソッド同様、get, post, put, patch, deleteを定義
    get "List all todos" do
      tags "Todos"
      produces "application/json"
      response "200", "todos found" do
        schema type: :array,
          items: {
            id: { type: :integer },
            title: { type: :string },
            created_at: { type: :string },
            updated_at: { type: :string }
          },
          required: ["id", "title", "created_at", "updated_at"]

        run_test!
      end
    end
  end

run_test! を実行することで、例えば上記の場合は /api/v1/todos にアクセスすることでステータスが200であること、レスポンス定義が一致することのチェックをしてくれる。

テスト実行コマンド

bundle exec rspec

試しにshowのエンドポイントを作成し、requiredの項目をレスポンスから除外してテストを実行するとちゃんと検知した

OpenAPIの定義生成と確認

上記のRSpec実装、コマンド実行でOpenAPIの定義が自動生成される。

rails rswag

設定で変更可能だが、デフォルトだと以下のファイルが自動生成される。

/swagger/v1/swagger.yaml
---
openapi: 3.0.1
info:
  title: API V1
  version: v1
paths:
  "/api/v1/todos":
    get:
      summary: List all todos
      tags:
      - Todos
      responses:
        '200':
          description: todos found
          content:
            application/json:
              schema:
                type: array
                items:
                  id:
                    type: integer
                  title:
                    type: string
                  created_at:
                    type: string
                  updated_at:
                    type: string
                required:
                - id
                - title
                - created_at
                - updated_at

rails g rswag:install を実行したタイミングで routes.rb に以下のルーティングが追加される。

routes.rb
mount Rswag::Ui::Engine => '/api-docs'
mount Rswag::Api::Engine => '/api-docs'

Rails Serverを起動して以下のページにアクセス

rails s

Swagger UIで定義を閲覧することができる

参考

サンプルリポジトリ

作成者以外のコメントは許可されていません