使用rswag生成Swagger文档时出现path方法未定义的NoMethodError

我编写了用于生成Swagger文档的Ruby代码：

require 'swagger_helper'

RSpec.describe 'Transactions API', swagger_doc: 'v1/swagger.yaml' do
  path '/transactions' do
    get 'List transactions' do
      tags 'Transactions'
      produces 'application/json'
      parameter name: :user_id, in: :query, type: :integer, description: 'User ID (optional)'

      response '200', 'transactions listed' do
        schema type: :array, items: {
          type: :object,
          properties: {
            transaction_id: { type: :integer },
            user_id: { type: :integer },
            from_currency: { type: :string },
            to_currency: { type: :string }
          }
        }
        run_test!
      end
    end
  end   
end

执行命令bundle exec rake rswag:specs:swaggerize生成文档时，出现以下错误：

$ bundle exec rake rswag:specs:swaggerize
/home/dalton/.rbenv/versions/3.4.4/bin/ruby -I/home/dalton/workspace/ror/ruby/3.4.0/gems/rspec-core-3.13.4/lib:/home/dalton/workspace/ror/ruby/3.4.0/gems/rspec-support-3.13.4/lib /home/dalton/workspace/ror/ruby/3.4.0/gems/rspec-core-3.13.4/exe/rspec --pattern spec/requests/\*\*/\*_spec.rb,\ spec/api/\*\*/\*_spec.rb,\ spec/integration/\*\*/\*_spec.rb --format Rswag::Specs::SwaggerFormatter --dry-run --order defined
DEPRECATION WARNING: Rswag::Ui: WARNING: The method will be renamed to "openapi_endpoint" in v3.0 (called from block in <main> at /home/dalton/workspace/ror/curconv/config/initializers/rswag_ui.rb:11)
Generating Swagger docs ...

An error occurred while loading ./spec/integration/transactions_swagger_spec.rb.
Failure/Error:
    path '/transactions' do
      get 'List transactions' do
        tags 'Transactions'
        produces 'application/json'
        parameter name: :user_id, in: :query, type: :integer, description: 'User ID (optional)'
  
        response '200', 'transactions listed' do
          schema type: :array, items: {
            type: :object,
            properties: {

NoMethodError:
  undefined method 'path' for class RSpec::ExampleGroups::TransactionsAPI
# ./spec/integration/transactions_swagger_spec.rb:4:in 'block in <main>'
# ./spec/integration/transactions_swagger_spec.rb:3:in '<main>'
Swagger doc generated at /home/dalton/workspace/ror/curconv/swagger/v1/swagger.yaml

Finished in 0.00006 seconds (files took 1.15 seconds to load)
0 examples, 0 failures, 1 error occurred outside of examples

解决步骤 #

这个错误的核心原因是Rswag的DSL方法（比如path）没有被RSpec正确加载，按以下步骤排查修复：

• 确认rswag-specs gem已安装
  检查Gemfile中是否包含gem 'rswag-specs'，如果没有就添加，然后执行bundle install完成安装。

• 配置RSpec加载Rswag DSL
  打开spec/rails_helper.rb（或spec/spec_helper.rb），添加以下配置：

  require 'rswag/specs'
  
  RSpec.configure do |config|
    # 引入Rswag的辅助方法
    config.include Rswag::Specs::Helpers
    # 为请求类型的测试扩展Rswag的DSL
    config.extend Rswag::Specs::ControllerHelpers, type: :request
  end
  

• 给spec文件指定测试类型
  在RSpec.describe块中添加type: :request，确保RSpec识别这是请求类型的测试，从而加载对应的Rswag DSL：

  require 'swagger_helper'
  
  RSpec.describe 'Transactions API', type: :request, swagger_doc: 'v1/swagger.yaml' do
    # 原有代码保持不变
  end
  

• 验证文件路径符合扫描规则
  Rswag默认会扫描spec/requests、spec/api、spec/integration目录下的*_spec.rb文件，你的文件放在spec/integration下是符合要求的。如果使用了自定义路径，需要在spec/swagger_helper.rb中配置扫描路径。

完成以上步骤后，重新执行bundle exec rake rswag:specs:swaggerize即可正常生成Swagger文档。

内容的提问来源于stack exchange，提问作者Dalton Cézane