如何实现API文档权限控制：仅管理员可见部分端点？

当然可以给API文档添加角色权限限制，分管理员和用户角色的需求完全能实现，下面按常用的API文档工具和自定义场景给出具体做法：

一、Swagger/OpenAPI 场景 #

这是最主流的API文档规范，实现步骤如下：

1. 在规范里定义角色权限
   在OpenAPI的YAML/JSON配置中，先添加认证方案（比如JWT），再给每个端点绑定允许访问的角色：

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []
paths:
  /admin/dashboard:
    get:
      summary: 管理员专属数据看板
      security:
        - bearerAuth: ["admin"]
      responses:
        '200':
          description: 返回管理员数据
  /user/profile:
    get:
      summary: 用户个人信息接口
      security:
        - bearerAuth: ["user", "admin"]
      responses:
        '200':
          description: 返回用户信息

2. 后端校验角色
   在后端服务里（比如Node.js、Java），解析用户的JWT Token，提取角色字段，判断是否匹配当前端点要求的角色，不匹配则返回403权限错误。
3. Swagger UI 动态隐藏无权限端点
   如果要在UI层面直接隐藏用户无权查看的端点，可以用Swagger UI的自定义脚本，根据当前用户角色过滤paths：

// 初始化Swagger UI时添加逻辑
const ui = SwaggerUIBundle({
  url: "/openapi.yaml",
  dom_id: '#swagger-ui',
  onComplete: function() {
    const userRole = localStorage.getItem('userRole'); // 从本地存储或接口获取角色
    const paths = ui.spec.paths;
    // 遍历所有端点，删除无权限的
    Object.keys(paths).forEach(path => {
      const requiredRoles = paths[path].get?.security?.[0]?.bearerAuth || [];
      if (!requiredRoles.includes(userRole) && !requiredRoles.includes('admin')) {
        delete paths[path];
      }
    });
    ui.spec.paths = paths;
    ui.updateSpec(ui.spec);
  }
});

二、Redoc 场景 #

Redoc是另一种常用的API文档渲染工具，实现方式类似：

1. 先在OpenAPI规范里定义角色权限
   和Swagger的配置一致，给端点绑定对应角色。
2. 自定义渲染逻辑过滤端点
   在Redoc初始化时，通过钩子函数根据用户角色过滤内容：

Redoc.init(
  '/openapi.yaml',
  {
    onLoaded: (api) => {
      const userRole = getCurrentUserRole(); // 自定义函数获取当前用户角色
      // 过滤出当前角色有权限的端点
      const filteredPaths = {};
      Object.keys(api.spec.paths).forEach(path => {
        const pathItem = api.spec.paths[path];
        const requiredRoles = pathItem.get?.security?.[0]?.bearerAuth || [];
        if (requiredRoles.includes(userRole) || requiredRoles.includes('admin')) {
          filteredPaths[path] = pathItem;
        }
      });
      api.spec.paths = filteredPaths;
      api.render();
    }
  },
  document.getElementById('redoc-container')
);

三、自定义API文档服务场景 #

如果是自己开发的文档页面，灵活性更高：

• 用户登录与角色存储：先做登录流程，把用户角色存在Session或Token中。
• 端点分组管理：把所有API端点分成「管理员组」和「用户组」，可以存在数据库或配置文件里。
• 动态渲染页面：根据当前登录用户的角色，只渲染对应组的端点列表和详细文档。
• 后端二次校验：无论前端是否隐藏端点，后端在处理实际API请求时必须再次校验用户角色，防止恶意访问。

内容的提问来源于stack exchange，提问作者Fatih Doğan