深入解析Redocly CLI：构建包含授权信息的本地API文档

本文旨在解决redoc在加载受授权保护的api schema时遇到的挑战。通过详细阐述如何利用redocly cli工具，在本地预先生成完整的api文档html文件，从而规避浏览器端授权请求的限制。这种方法允许开发者在有权限的环境中获取api schema，并将其转换为静态文档，最终实现无缝部署和访问，无需客户端再次进行授权验证。

Redoc与受保护API Schema的挑战

在使用Redoc standalone展示API文档时，如果API schema文件（如schema.yaml）托管在一个需要Authorization头才能访问的私有API服务器上，Redoc默认的客户端请求机制将无法自动包含此授权信息。这意味着，即使页面加载了redoc.standalone.js，尝试通过spec-url属性（例如spec-url='https://api.example.com/schema.yaml'）去获取schema时，请求也会因缺少授权而被服务器拒绝，导致API文档无法正常渲染。

传统的解决方案，如尝试在浏览器端拦截请求并添加授权头，或修改Redoc内部的请求逻辑，通常复杂且不易维护。更优的策略是避免在客户端直接请求受保护的schema，转而采用预处理的方式。

解决方案：利用Redocly CLI进行静态文档生成

Redocly官方提供了一个强大的命令行工具redocly/cli，它允许开发者在本地环境中构建和验证API文档。核心思想是：在拥有访问API schema权限的环境中，先将schema文件下载到本地，然后使用redocly build-docs命令，将本地的schema文件直接编译成一个完整的静态HTML文档。这样生成的HTML文件包含了渲染API文档所需的所有数据和逻辑，无需在客户端运行时再次发起对schema的远程请求。

1. 安装Redocly CLI

首先，确保你的开发环境中安装了Node.js和npm（或yarn）。然后，通过npm全局安装Redocly CLI：

npm install -g @redocly/cli

或者，如果你更喜欢在项目本地安装：

npm install --save-dev @redocly/cli

安装完成后，你可以通过运行redocly --version来验证安装是否成功。

2. 获取API Schema文件

这是关键一步。你需要在一个能够提供Authorization头访问API服务器的环境中，将schema.yaml文件下载到本地。这通常可以通过curl、Postman或其他HTTP客户端工具完成。

示例：使用curl下载受保护的schema

微信 WeLM

WeLM不是一个直接的对话机器人，而是一个补全用户输入信息的生成模型。

33

查看详情

假设你的API服务器在https://api.example.com/schema.yaml提供schema，并且需要一个Bearer Token进行授权：

curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" https://api.example.com/schema.yaml -o schema.yaml

请将YOUR_AUTH_TOKEN替换为你的实际授权令牌。执行此命令后，schema.yaml文件将被保存到当前目录下。

3. 构建静态HTML文档

一旦schema.yaml文件在本地可用，你就可以使用redocly build-docs命令来生成静态HTML文档。

redocly build-docs schema.yaml -o index.html

• schema.yaml：这是你刚刚下载到本地的API schema文件。
• -o index.html：指定输出的HTML文件名。你可以根据需要更改此名称。

执行此命令后，redocly/cli会读取schema.yaml文件，并生成一个名为index.html的完整静态HTML文件。这个文件包含了所有渲染API文档所需的JavaScript、CSS和数据，是一个独立的、可直接部署的文档。

4. 部署和发布

现在，你只需将生成的index.html文件（以及可能由Redocly CLI生成的其他相关静态资源，如果你的配置更复杂的话，但对于默认build-docs通常是单个HTML文件）部署到任何静态文件服务器上即可。用户访问这个HTML文件时，将直接看到完整的API文档，而无需浏览器再次向私有API服务器发起请求。

优势与注意事项

1. 规避授权问题： 彻底解决了客户端无法携带授权头访问私有API schema的问题。
2. 静态部署： 生成的文档是纯静态HTML，可以轻松部署到CDN、GitHub Pages、Netlify等任何静态托管服务，提供快速、可靠的访问。
3. 性能优化： 客户端无需等待schema下载，直接加载完整文档，提升用户体验。
4. CI/CD集成： 此流程非常适合集成到持续集成/持续部署(CI/CD)管道中。每次API schema更新时，CI/CD系统可以自动下载最新schema，重新构建文档，并部署。
5. 版本控制： 将schema文件和生成的文档都纳入版本控制，有助于追踪文档变更。

注意事项：

• 确保你在构建文档时使用的schema.yaml是最新的，以避免文档与实际API不一致。
• 如果你的schema.yaml中包含敏感信息，请确保部署环境的安全性。
• 对于大型API，构建过程可能需要一些时间，但在生产环境中，这种预构建的优势远大于构建时间。

总结

通过采用redocly build-docs命令进行静态文档生成，开发者可以优雅地解决Redoc在展示受授权保护的API schema时遇到的挑战。这种方法不仅简化了部署流程，提高了文档访问的可靠性和性能，还为CI/CD集成提供了便利，是管理和发布私有API文档的推荐实践。

以上就是深入解析Redocly CLI：构建包含授权信息的本地API文档的详细内容，更多请关注php中文网其它相关文章！