如何在Redocly中仅展示API端点的Required Scopes

要在Redocly生成的文档里只保留每个端点的Required Scopes，隐藏Flow Type、Token URL和全局Scopes，可以从OpenAPI文档调整和Redocly自定义渲染两个层面入手，以下是具体方案：

一、确保OpenAPI文档的权限配置正确 #

首先确认你的C#代码通过SwaggerRequiredScopes特性生成的OpenAPI文档，每个端点的security字段已正确关联所需权限，示例结构如下：

paths:
  /api/your-resource:
    get:
      security:
        - OAuth2: ['read:your-resource']
      # 其他端点配置
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      scopes:
        read:your-resource: 读取资源权限
        write:your-resource: 写入资源权限
      # 可保留或移除flow、tokenUrl，后续通过Redocly隐藏

二、使用Redocly自定义主题隐藏多余元素 #

最可靠的方式是通过Redocly的自定义主题组件，覆盖默认的权限渲染逻辑，只展示Required Scopes：

1. 创建自定义主题文件（比如custom-theme.js）

import { AuthMethod } from 'redoc';

export default {
  components: {
    AuthMethod: ({ auth, isRequired }) => {
      // 仅渲染当前端点要求的权限
      if (!auth?.scopes || !isRequired) return null;
      
      // 筛选出当前端点实际需要的scopes
      const requiredScopes = Object.entries(auth.scopes).filter(([scope]) => {
        return auth.requiredScopes?.includes(scope);
      });

      return (
        <div className="auth-method">
          <h4>Required Scopes</h4>
          <ul>
            {requiredScopes.map(([scope, desc]) => (
              <li key={scope}>{scope} {desc && `- ${desc}`}</li>
            ))}
          </ul>
        </div>
      );
    },
  },
};

2. 在Redocly配置文件（redocly.yaml）中引用自定义主题

theme:
  custom: ./custom-theme.js

三、可选：通过Redocly配置快速隐藏部分元素 #

如果不需要深度定制组件，也可以通过Redocly内置配置项直接隐藏指定元素，在redocly.yaml中添加：

redoc:
  hideAuthenticationFlow: true  # 隐藏Flow Type
  hideTokenUrl: true             # 隐藏Token URL
  hideScopes: true               # 隐藏全局Scopes列表

该方式会隐藏全局Scopes列表，但每个端点的Required Scopes仍会保留显示，适合轻量化需求场景。

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