如何使用Redocly CLI构建包含授权信息的本地API文档

Redocly CLI是一款基于OpenAPI规范生成高质量API文档的命令行工具，它支持将YAML或JSON格式的API定义文件转换为可交互的本地文档站点，同时可以灵活配置授权信息的展示逻辑，满足开发过程中接口调试和权限说明的需求。

Redocly CLI安装与基础配置

首先需要在本地环境中安装Redocly CLI，它依赖Node.js运行环境，因此需要先确保本地已经安装了Node.js 14及以上版本。安装完成后可以通过npm命令全局安装Redocly CLI：

# 全局安装Redocly CLI
npm install -g @redocly/cli

# 验证安装是否成功，查看版本号
redocly --version

安装完成后，可以通过redocly init命令初始化一个Redocly项目，该命令会引导你选择API定义文件的路径，并生成基础的配置文件redocly.yaml，后续构建文档的相关配置都可以在这个文件中调整。

OpenAPI文件中定义授权信息

要在生成的文档中展示授权信息，首先需要在OpenAPI规范文件中正确定义安全方案。OpenAPI支持多种常见的授权类型，包括API Key、Bearer Token、OAuth2等，下面是几种常见授权类型的定义示例：

API Key授权定义

openapi: 3.0.3
info:
  title: 示例API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: 成功返回用户列表
components:
  securitySchemes:
    # 定义API Key类型授权
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 请求头中携带的API密钥，用于接口身份验证

Bearer Token授权定义

components:
  securitySchemes:
    # 定义Bearer Token类型授权
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 使用JWT格式的Bearer Token进行授权，Token需要放在Authorization请求头中

OAuth2授权定义

components:
  securitySchemes:
    # 定义OAuth2类型授权
    OAuth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://ipipp.com/oauth/authorize
          tokenUrl: https://ipipp.com/oauth/token
          scopes:
            read:users: 读取用户信息权限
            write:users: 修改用户信息权限
      description: OAuth2授权流程，支持授权码模式

定义好安全方案后，可以在全局或者单个接口路径下通过security字段引用对应的授权方案，这样生成的文档就会自动展示对应的授权说明。

构建包含授权信息的本地文档

完成OpenAPI文件的授权定义后，就可以使用Redocly CLI构建本地文档了。基础的构建命令如下：

# 构建本地文档，指定API定义文件和输出目录
redocly build-docs openapi.yaml -o ./docs

如果需要自定义授权模块的展示样式，可以在redocly.yaml配置文件中添加主题相关的配置：

# redocly.yaml配置示例
theme:
  colors:
    primary:
      main: '#1a73e8'
  typography:
    fontSize: '14px'
  security:
    # 自定义授权模块的标题
    sectionTitle: '接口授权说明'
    # 是否默认展开授权说明模块
    defaultExpanded: true

构建完成后，进入输出的docs目录，打开index.html文件就可以看到本地运行的API文档，文档中会清晰展示所有定义的授权类型、授权位置、参数说明等信息，开发者可以直接在文档页面填写对应的授权参数进行接口调试。

本地文档的启动与调试

如果需要实时预览文档修改效果，可以使用Redocly CLI的开发服务器命令：

# 启动本地开发服务器，实时监听文件变化
redocly preview-docs openapi.yaml

该命令会启动一个本地服务，默认端口为4000，访问http://127.0.0.1:4000就可以查看文档，修改OpenAPI文件或者配置文件后，页面会自动刷新，方便快速调整授权信息的展示效果。

注意事项

• 不要在公开的OpenAPI文件中写入真实的授权密钥或者敏感Token，仅保留授权类型的定义说明即可
• 如果API需要多种授权方式，可以在security字段中定义多个授权方案的数组，文档会展示所有可选的授权方式
• Redocly CLI支持自定义HTML模板，如果需要更复杂的授权模块交互，可以自定义模板文件并在构建时指定模板路径

Redocly CLI的授权信息展示完全遵循OpenAPI规范的定义，因此只要按照规范正确编写安全方案，就可以自动生成准确的授权说明模块，不需要额外手动编写前端代码。

Redocly_CLIAPI文档授权信息本地构建修改时间：2026-06-23 10:45:41