在使用Redoc生成API文档的过程中，远程API Schema通常需要携带认证信息才能访问，直接配置远程Schema地址会导致Redoc无法拉取文件，文档无法正常渲染。通过本地构建的方式，我们可以将远程Schema文件提前下载到本地，绕过认证限制完成文档生成。
问题背景
很多企业的API Schema部署在内网或者需要Bearer Token、Basic Auth等认证方式才能访问的服务器上，Redoc默认会直接请求配置的Schema地址，不会自动携带认证信息，因此会出现403、401等错误，导致文档加载失败。如果直接修改Redoc的源码添加认证逻辑，会增加维护成本，本地构建是更轻量的解决方案。
本地构建实现步骤
1. 获取远程API Schema文件
首先我们需要通过带认证的方式获取远程Schema文件，比如使用curl命令携带Token下载：
# 携带Bearer Token下载远程Schema curl -H "Authorization: Bearer your_token_here" https://api.ippipp.com/schema.json -o local_schema.json
下载完成后，将local_schema.json放到Redoc项目的根目录下。
2. 配置Redoc使用本地Schema路径
如果是使用Redoc的官方CLI工具构建文档，只需要在配置文件中将Schema地址改为本地相对路径即可。如果是通过HTML直接引入Redoc，修改spec-url属性为本地路径：
<!DOCTYPE html>
<html>
<head>
<title>API文档</title>
<link rel="stylesheet" href="https://cdn.redoc.ly/redoc/latest/bundles/redoc.min.css" />
</head>
<body>
<redoc spec-url="./local_schema.json"></redoc>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>
3. 启动本地服务验证文档
如果直接打开HTML文件可能会因为浏览器同源策略导致本地Schema加载失败，需要启动一个简单的本地HTTP服务，比如使用Node.js的http-server：
# 安装http-server npm install -g http-server # 在项目根目录启动服务，端口设置为3000 http-server -p 3000
打开浏览器访问http://127.0.0.1:3000，即可看到正常渲染的API文档，不再受远程认证限制。
本地构建的优势
- 完全绕过远程Schema的认证限制，不需要修改Redoc的认证逻辑
- 本地Schema加载速度更快，不受远程服务器网络波动影响
- 可以对本地Schema做二次修改，比如补充示例、调整描述，再生成文档
- 适合内网环境使用，不需要开放远程Schema的公网访问权限
注意事项
需要注意的是，远程Schema如果会定期更新，本地构建的Schema不会自动同步，需要定期重新下载更新本地文件。如果Schema更新频率较高，可以编写一个定时脚本，自动携带认证信息下载最新Schema，再触发Redoc的重新构建，保证文档内容的时效性。
另外，本地的Schema文件需要注意权限控制，避免敏感接口信息泄露，尤其是如果文档需要部署到公网环境，需要确认Schema中不包含未脱敏的敏感数据。
RedocAPI_Schema本地构建认证修改时间：2026-07-05 20:00:24