前提

rswagの公式Docを見ながらAPI仕様書の自動作成に取り組んでいた時の話。
自動作成までの手順として、RSpecでAPIのテストを書いた後、ターミナルでRAILS_ENV=test rake rswag:specs:swaggerizeを実行する。
すると、swagger/v1/swagger.yaml が自動で作成されて、api-docs/index.html にアクセスするとswaggerのAPIDocが確認できる。

うまく行ったこと

createアクションはドキュメント通りに以下のようなテストを作った。（ユーザーに関するAPI）

users_spec.rb

require 'swagger_helper'

RSpec.describe 'api/v1/users', type: :request do
  path '/api/v1/users' do
    post('create user') do
      # リクエストボディがJSON形式であることを示す
      consumes 'application/json'
      parameter name: :user, in: :body, schema: {
        type: :object,
        properties: {
          name: { type: :string },
          email: { type: :string },
          password: { type: :string }
        },
        required: [:name, :email, :password]
      }

      response '201', 'user created' do
        let(:user) { { name: 'test_user', email: 'test@example.com', password: 'test_pass' } }
        run_test!
      end

      response '422', 'パスワード無しでリクエスト' do
        let(:user) { { name: 'test_user', email: 'test@example.com' } }
        run_test!
      end
    end
  end
end

RAILS_ENV=test rake rswag:specs:swaggerizeを実行すると、

swgger.yamlが作成された。

swagger.yaml

---
openapi: 3.0.1
info:
  title: API V1
  version: v1
paths:
  "/api/v1/users":
    post:
      summary: create user
      parameters: []
      responses:
        '201':
          description: user created
        '422':
          description: パスワード無しでリクエスト
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
                password:
                  type: string
              required:
              - name
              - email
              - password
servers:
- url: https://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000

api-docs/index.html にアクセスしてみると、ちゃんとプロパティも反映された状態で確認できた。

困ったこと

indexアクションのテストの書き方の参考が公式Docにはありませんでした。自分流に書いたのですが、上画像のプロパティ欄がなかなか表示されませんでした。
僕に公式Docを読み解く力があれば解決できたかもしれないのですが。。。まだまだ苦手です。
一人で試行錯誤しました。

解決策

海外で同じことで苦しんだ人がいました。バージョンダウンするだけでした、何じゃそりゃ、、、

Just replace opeanapi: '3.0.1' for swagger: '2.0'. I've faced this same issue and this is the only workaround I've found so far.

swagger_helper.rb

RSpec.configure do |config|
  config.openapi_root = Rails.root.join('swagger').to_s

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