如何在Rails项目中用rswag生成多命名空间API文档？

一、拆分swagger配置文件 #

创建两个独立的swagger配置文件，对应两个命名空间，放在项目根目录的swagger文件夹下：

1. 后台管理API配置（swagger/admin/v1/swagger.yml） #

openapi: 3.0.1
info:
  title: 后台管理API文档
  version: v1
paths: {}
components: {}
servers:
  - url: http://localhost:3000/admin/v1

2. 公共服务API配置（swagger/api/v1/swagger.yml） #

openapi: 3.0.1
info:
  title: 公共服务API文档
  version: v1
paths: {}
components: {}
servers:
  - url: http://localhost:3000/api/v1

二、配置swagger_helper.rb关联文档与测试文件 #

在spec/swagger_helper.rb中定义两份文档的生成规则，指定各自对应的测试文件范围：

RSpec.configure do |config|
  config.swagger_root = Rails.root.to_s + '/swagger'

  # 定义两份文档的基础信息
  config.swagger_docs = {
    'admin/v1/swagger.yml' => {
      openapi: '3.0.1',
      info: { title: '后台管理API V1', version: 'v1' },
      paths: {},
      servers: [{ url: 'http://localhost:3000/admin/v1' }]
    },
    'api/v1/swagger.yml' => {
      openapi: '3.0.1',
      info: { title: '公共服务API V1', version: 'v1' },
      paths: {},
      servers: [{ url: 'http://localhost:3000/api/v1' }]
    }
  }

  config.swagger_format = :yaml
end

三、测试文件绑定对应文档 #

在已划分好的两个测试文件夹（比如spec/requests/admin和spec/requests/api）的测试文件中，通过swagger_doc指定所属文档：

Admin测试文件示例（spec/requests/admin/users_spec.rb） #

RSpec.describe 'Admin/Users', type: :request do
  path '/admin/v1/users' do
    get('获取用户列表') do
      tags '用户管理'
      produces 'application/json'

      response(200, '请求成功') do
        run_test!
      end
    end
  end

  # 绑定到Admin API文档
  swagger_doc 'admin/v1/swagger.yml'
end

公共API测试文件示例（spec/requests/api/posts_spec.rb） #

RSpec.describe 'Api/Posts', type: :request do
  path '/api/v1/posts' do
    get('获取文章列表') do
      tags '文章服务'
      produces 'application/json'

      response(200, '请求成功') do
        run_test!
      end
    end
  end

  # 绑定到公共API文档
  swagger_doc 'api/v1/swagger.yml'
end

四、自动生成两份文档 #

执行rswag生成命令，工具会根据配置和测试文件的绑定关系，自动生成两份独立的swagger文档：

bundle exec rswag

生成后，两份文档会分别存放在swagger/admin/v1/swagger.yml和swagger/api/v1/swagger.yml路径下。

五、路由中挂载双文档UI #

在config/routes.rb中配置两个rswag UI实例，分别对应两份文档：

Rails.application.routes.draw do
  # 后台管理API文档路由
  mount Rswag::Ui::Engine => '/admin/docs'
  mount Rswag::Api::Engine => '/admin/docs'
  Rswag::Ui::Engine.configure do |c|
    c.swagger_endpoint '/admin/v1/swagger.yml', '后台管理API V1文档'
  end

  # 公共服务API文档路由
  mount Rswag::Ui::Engine => '/api/docs'
  mount Rswag::Api::Engine => '/api/docs'
  Rswag::Ui::Engine.configure do |c|
    c.swagger_endpoint '/api/v1/swagger.yml', '公共服务API V1文档'
  end

  # 你的业务命名空间路由
  namespace :admin do
    namespace :v1 do
      # 业务路由定义
    end
  end

  namespace :api do
    namespace :v1 do
      # 业务路由定义
    end
  end
end

完成后，访问http://localhost:3000/admin/docs即可查看后台管理API文档，访问http://localhost:3000/api/docs查看公共服务API文档。

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