Grape/grape-swagger嵌套资源路径如何在Swagger文档拆分至不同板块

grape-swagger默认会将接口按最外层命名空间自动生成分类标签，你当前所有接口挂载在users命名空间下，所以默认都归类到users板块，可通过以下两种方式自定义分类：

方法1：为每个子API类单独指定标签 #

在每个被挂载的子API类头部添加swagger_tag配置即可，示例如下：

用户认证API配置 #

# app/api/v1/users/auth_api.rb
class V1::Users::AuthAPI < Grape::API
  swagger_tag name: '用户认证', description: '用户登录、注册、Token管理相关接口'

  # 原有逻辑
  namespace :auth do
    # 接口定义
  end
end

用户素材API配置 #

# app/api/v1/users/materials_api.rb
class V1::Users::MaterialsAPI < Grape::API
  swagger_tag name: '用户素材', description: '用户素材上传、查询、删除相关接口'

  # 原有逻辑
  namespace :materials do
    # 接口定义
  end
end

方法2：全局配置路径匹配规则生成标签 #

如果你不想逐个修改子API类，可以在根API的grape-swagger初始化配置中添加路径解析规则，自动按路径分配标签：

# 根API类中swagger配置部分
add_swagger_documentation \
  # 预定义所有标签的说明
  tags: [
    { name: '用户认证', description: '用户认证相关接口' },
    { name: '用户素材', description: '用户素材相关接口' },
    { name: '用户相关', description: '其他用户通用接口' }
  ],
  # 自定义标签解析逻辑
  tag_path_parser: -> (request_path) {
    path_segments = request_path.split('/')
    return '用户素材' if path_segments.include?('materials')
    return '用户认证' if path_segments.include?('auth')
    '用户相关'
  },
  # 保留你原有其他swagger配置
  base_path: '/api/v1',
  hide_documentation_path: true

补充：单个接口自定义分类 #

如果需要将某个接口归到多个分类，也可以在接口定义时单独指定tags参数：

namespace :materials do
  desc '获取公开素材列表', tags: ['用户素材', '公共资源']
  get 'public' do
    # 接口逻辑
  end
end

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