本教程旨在解决redoc standalone在加载需要认证的远程api schema时遇到的授权问题。通过介绍`redocly build-docs`命令行工具，我们展示了如何预先下载受保护的api schema并在本地生成静态html文档，从而避免了redoc客户端直接访问带有授权限制的远程资源，实现了文档的离线展示和便捷部署。
Redoc静态文档生成：解决受保护API Schema访问问题
在使用Redoc standalone展示API文档时，一个常见场景是API schema文件（如schema.yaml或openapi.json）托管在需要身份认证的服务器上。Redoc默认通过spec-url属性从远程URL获取schema，但其客户端加载机制通常不包含发送自定义的Authorization头。这导致Redoc无法成功获取受保护的schema文件，从而无法正常渲染API文档。
本文将详细介绍一种推荐的解决方案：利用Redocly CLI工具预先构建静态HTML文档，彻底规避客户端授权问题。
遇到的问题分析
当Redoc standalone通过标签尝试加载schema时，它会发起一个HTTP GET请求到指定的URL。如果api.example.com上的schema.yaml需要一个Authorization头（例如Bearer Token），而Redoc的JavaScript运行时没有机制来自动添加这个头，那么请求就会失败，导致API文档无法显示。
直接在浏览器环境中尝试修改Redoc的内部请求逻辑以添加授权头通常是复杂且不推荐的，因为它涉及到深入Redoc的实现细节，并且可能在Redoc更新后失效。
解决方案：使用Redocly CLI预构建文档
解决此问题的最佳实践是利用Redocly CLI提供的build-docs命令。这个方法的核心思想是在文档生成阶段，即在本地或CI/CD环境中，手动获取API schema文件，然后使用Redocly CLI将其编译成静态HTML文档。这样，最终部署的HTML文件就不再需要从远程服务器动态获取schema，从而完全避免了客户端授权的问题。
1. 前提条件
在开始之前，请确保您的系统已安装Node.js和npm（或yarn）。
2. 安装Redocly CLI
首先，您需要全局安装Redocly CLI工具：
Vizard
AI驱动的视频编辑器
101 查看详情 
npm install -g @redocly/cli
或者使用yarn：
yarn global add @redocly/cli
3. 获取受保护的API Schema文件
这是解决问题的关键步骤。在本地环境中，您可以手动或通过脚本使用适当的授权凭证下载API schema文件。例如，如果您的API需要一个Bearer Token：
# 替换 YOUR_TOKEN 为您的实际授权令牌# 替换 https://api.example.com/schema.yaml 为您的API schema URLcurl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/schema.yaml -o schema.yaml
执行此命令后，schema.yaml文件将被下载并保存在当前目录下。
4. 使用Redocly CLI生成静态文档
一旦您有了本地的schema.yaml文件，就可以使用redocly build-docs命令生成静态HTML文档：
redocly build-docs schema.yaml -o index.html
schema.yaml: 指定本地的API schema文件路径。-o index.html: 指定输出的HTML文件名。Redocly CLI会生成一个包含所有必要CSS、JavaScript和API文档内容的独立HTML文件。
5. 部署生成的HTML文档
现在，index.html文件以及可能生成的其他静态资源（如果您的配置需要）已经包含了完整的API文档。您可以将这些文件部署到任何静态文件服务器（如Nginx, Apache, GitHub Pages, Netlify等），用户访问时将直接加载这些静态内容，无需再向API服务器发起schema请求。
优势与注意事项
优势
解决授权问题： 彻底避免了Redoc客户端在加载schema时遇到的授权难题。性能提升： 用户访问时直接加载本地静态文件，无需等待远程schema下载和解析，提升了加载速度。离线可用性： 生成的文档可以完全离线访问，无需网络连接即可查看。简化部署： 部署过程变为简单的静态文件托管。版本控制： API schema文件可以纳入版本控制系统，与文档同步管理。
注意事项
构建步骤： 这种方法引入了一个构建步骤。每次API schema更新时，都需要重新执行下载和构建命令来更新文档。环境依赖： 需要在构建环境中安装Node.js和Redocly CLI。这在CI/CD流水线中很容易集成。动态内容： 如果您的API schema是极其动态的，且需要实时反映最新状态（这种情况较少见），那么这种静态生成的方式可能需要更频繁的构建。然而，对于大多数API文档而言，这是一个可接受甚至更优的策略。
总结
通过采用redocly build-docs命令预先生成静态API文档，我们有效地解决了Redoc standalone在访问受保护API schema时遇到的授权挑战。这种方法不仅规避了客户端授权的复杂性，还带来了性能提升、离线可用性和简化部署等多重优势，是构建和发布专业API文档的推荐实践。
以上就是Redoc静态文档生成：解决受保护API Schema访问问题的详细内容，更多请关注创想鸟其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/870201.html
微信扫一扫 
支付宝扫一扫 
