本文旨在解决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
ONLYOFFICE
用ONLYOFFICE管理你的网络私人办公室
1027 查看详情 
假设你的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服务器发起请求。
优势与注意事项
规避授权问题： 彻底解决了客户端无法携带授权头访问私有API schema的问题。静态部署： 生成的文档是纯静态HTML，可以轻松部署到CDN、GitHub Pages、Netlify等任何静态托管服务，提供快速、可靠的访问。性能优化： 客户端无需等待schema下载，直接加载完整文档，提升用户体验。CI/CD集成： 此流程非常适合集成到持续集成/持续部署(CI/CD)管道中。每次API schema更新时，CI/CD系统可以自动下载最新schema，重新构建文档，并部署。版本控制： 将schema文件和生成的文档都纳入版本控制，有助于追踪文档变更。
注意事项：
确保你在构建文档时使用的schema.yaml是最新的，以避免文档与实际API不一致。如果你的schema.yaml中包含敏感信息，请确保部署环境的安全性。对于大型API，构建过程可能需要一些时间，但在生产环境中，这种预构建的优势远大于构建时间。
总结
通过采用redocly build-docs命令进行静态文档生成，开发者可以优雅地解决Redoc在展示受授权保护的API schema时遇到的挑战。这种方法不仅简化了部署流程，提高了文档访问的可靠性和性能，还为CI/CD集成提供了便利，是管理和发布私有API文档的推荐实践。
以上就是深入解析Redocly CLI：构建包含授权信息的本地API文档的详细内容，更多请关注创想鸟其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/870106.html
微信扫一扫 
支付宝扫一扫 
