Ruby on Rails 6中使用rswag编写API GET请求文档及测试数据返回问题

核心误区澄清 #

先明确rswag的两个独立能力，这是你遇到问题的核心原因：

• 作为RSpec扩展跑接口测试：执行你写的测试代码时走测试环境，操作测试数据库，FactoryBot创建的数据仅在测试执行时存在，跑完会自动清理
• 生成Swagger文档提供「Try it out」能力：该功能会直接请求你swagger_helper.rb中servers配置的地址（你这里是http://localhost:3000，默认是开发环境启动的服务），请求的是开发数据库的数据，和你写的RSpec测试代码完全无关

你现有代码的问题修正 #

你当前的测试代码不会生成测试数据，因为let(:create_activities)定义的变量没有被触发执行，修正后的测试代码如下：

require 'swagger_helper'

RSpec.describe 'Activities API', type: :request do
  path '/api/activities' do
    get 'Lists all activities' do
      tags 'activities'
      produces 'application/json'

      response '200', 'lists activities' do
        # 执行前创建10条测试数据，仅作用于测试环境
        before { create_list(:activity, 10) }
        schema type: :object,
               properties: {
                 activities: {
                   type: :array,
                   items: {
                     properties: {
                       id: { type: :integer },
                       name: { type: :string },
                       content: { type: :string },
                       image: { type: :string }
                     },
                     required: %w[id name content]
                   }
                 }
               }
        run_test!
      end
    end
  end
end

修正后执行rake rswag:specs:swaggerize生成文档时，测试会正常通过，也不会影响开发库数据。

实现「Try it out」返回至少5条数据的方案 #

方案1：开发库插入测试数据（推荐，符合真实请求逻辑） #

直接在开发环境创建持久化的活动数据，步骤：

1. 终端执行rails c进入开发环境控制台
2. 执行FactoryBot.create_list(:activity, 10)，数据会写入开发数据库
3. 启动Rails开发服务后点击「Try it out」，就能直接返回10条活动数据

方案2：配置静态响应示例（不需要依赖数据库） #

如果不需要真实请求返回数据，只需要文档里展示响应示例，可以在响应配置里加example字段：

response '200', 'lists activities' do
  schema type: :object,
         properties: {
           # 你的schema配置不变
         }
  # 加静态示例
  example 'application/json', :default, {
    activities: [
      { id: 1, name: "活动1", content: "活动1内容", image: "xxx.jpg" },
      { id: 2, name: "活动2", content: "活动2内容", image: "yyy.jpg" }
      # 按需补充更多示例即可
    ]
  }
  run_test!
end

生成文档后用户打开接口就能看到示例响应，不需要修改数据库。

文档化范围参考 #

给你团队的新手参考，需要文档化的内容：

• 所有对外暴露的API路径、请求方法、标签分类
• 所有请求参数：路径参数、查询参数、请求体结构、必填项说明
• 所有响应：状态码、响应结构、错误场景说明
• 鉴权规则：哪些接口需要JWT、JWT的传参位置（Header/Query）、格式要求

不需要文档化的内容：

• 仅内部服务调用、不对外暴露的接口
• 业务逻辑的内部实现细节
• 非通用的极端异常场景

内容的提问来源于stack exchange，提问作者GuidoMedina