Redoc:把 OpenAPI 文档做得能看

Redoc 在 GitHub 上已经拿到 25.7K Star 了。

Redocly 开源的这一个工具，只做一件事：拿 OpenAPI 定义文件，吐出一份能直接看的 API 文档。支持 OpenAPI 3.1、3.0 和 Swagger 2.0，左边菜单、中间正文、右边示例的三栏布局，响应式适配各种屏幕。

1、 这玩意儿是干嘛的

就一件事：拿一份 OpenAPI 的 yaml 或 json，生成人能读的 API 文档。

丢一份 openapi.yaml 进去，输出一个 redoc-static.html，浏览器打开就能看。不用自己搭站点，不用写前端，文档默认就是三栏结构：左边搜索加导航，中间是接口说明，右边是请求和响应示例。菜单和正文滚动同步，看哪个接口，右边示例跟着切。

2、 为什么要用它

写过 OpenAPI 文档的人都知道，Swagger UI 自带的渲染效果属于能用但不好用这一档。文档一长，菜单平铺、跳转困难，移动端基本没法看。

Redoc 的三栏布局把导航、正文、示例各占一块，阅读路径很直接。再加上它原生支持 x-tagGroups 把标签按业务域分组，API 数量多的时候菜单不会糊成一锅。代码示例、可空字段、徽章这些扩展项也都通过 vendor extension 配置，不依赖额外的运行时。

3、 怎么用

最省事的方式是 npx 一行起步：

npx @redocly/cli build-docs openapi.yaml

默认生成 redoc-static.html，扔到任何静态托管上都能跑。

不想用 CLI 的话，直接在 HTML 里贴一对标签也能用：

<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc><script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>

spec-url 写成本地文件路径也行，库也可以 npm 装好之后从自己服务器上分发。React 项目里可以当成一个组件直接 import，集成进 create-react-app 不需要额外配置。

4、 能配什么

Redoc 走的是 vendor extension 路线，行为基本都在 OpenAPI 文件里通过 x- 字段控制：

• • x-logo 指定文档顶部 logo
• • x-tagGroups 给标签按业务域分组
• • x-codeSamples 给每个接口配代码示例
• • x-traitTag 把分页、限流这类横向标签从主菜单里拎出来
• • x-displayName 改菜单里显示的名字
• • x-servers 从 OpenAPI 3.0 反向移植的多服务器支持

主题和样式可配置项更多，配色、字体、菜单宽度、示例折叠状态都能调，具体看仓库 docs/config.md。

5、 Redoc 和 Redocly API Reference

Redoc 是社区版，Redocly 自己另有一套商业的 API Reference。商业版多了 try-it 控制台、自动代码生成、分页和更多主题选项。只想要一份好看的静态文档，社区版够了；要在线调试接口、要走商业化部署，再看 Redocly 的付费档。

6、 适合谁用

• • 后端写完接口、要给前端一份能看的文档的团队
• • 维护公共 API、需要把 OpenAPI 文档直接对外发布的开发者
• • 觉得 Swagger UI 长得不好看、想要更接近成品文档体感的项目
• • 内部有大量 OpenAPI 定义、想要批量生成静态文档站点的人