夜雨聆风
25.7k Star!API文档界的＂颜值天花板＂Redoc,Swagger UI瞬间不香了
写文档一时爽，维护文档火葬场。API文档这事，多少团队栽过跟头？
兄弟们，聊个扎心的话题——写API文档。
程序员圈子里流传着一条铁律：最讨厌两件事，一是写文档，二是别人不写文档。
为啥？因为文档这玩意儿，写的时候费劲，维护的时候更费劲。接口一更新，文档还是老的，前后端对不上，扯皮、甩锅、加班……懂的都懂。
但话说回来，API文档又是刚需。没有文档，前端怎么对接？第三方开发者怎么接入？总不能让人家去翻你的源码吧？
所以，Swagger 应运而生，从代码注解自动生成文档，一度成为行业标配。但 Swagger UI 那个界面……emmm，怎么说呢，功能是有的，但颜值嘛，确实有点”直男审美”。接口一多，找起来那叫一个费劲。
直到我遇到了今天的主角——Redoc。
它是什么？一句话说清楚
Redoc 是一个开源工具，专门用来把 OpenAPI（以前叫 Swagger）规范文件，渲染成颜值爆表、交互丝滑的 API 参考文档。
项目地址：https://github.com/redocly/redoc
凭什么它能火出圈？
三栏布局，信息一目了然
Redoc 默认采用三栏响应式布局：
-
左栏：搜索框 + 导航菜单，接口再多也不迷路 -
中栏：文档正文，参数说明、返回值结构清清楚楚 -
右栏：请求/响应示例，复制即用
这种布局有多爽？左边找接口，中间看说明，右边抄代码，三栏联动，丝滑得像德芙。
兼容性拉满
不管你用的是 OpenAPI 3.1、3.0，还是老牌的 Swagger 2.0，Redoc 通吃。从古早项目到最新规范，一把梭。
部署简单到离谱
方式一：一行命令生成静态 HTML
npx @redocly/cli build-docs openapi.yaml
输出一个 redoc-static.html，打开浏览器就能看，零依赖、零配置。
方式二：一个 HTML 标签搞定
<redocspec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
<scriptsrc="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
就这两行，API 文档直接嵌入你的页面。这比 Swagger UI 那套配置流程，不知道高到哪里去了。
高度可定制，品牌感拉满
Redoc 支持丰富的配置选项，你可以：
-
用 x-logo扩展放上公司 Logo -
用 x-tagGroups把接口按业务模块分组 -
用 x-codeSamples展示多语言代码示例 -
用 x-badges给接口打标签 -
自定义主题配色，匹配企业品牌风格
说白了，Swagger UI 给你的是一套模板，Redoc 给你的是一个可以”装修”的家。
快速上手：3分钟拥有自己的API文档
第一步：准备一个OpenAPI文件
如果你还没有，随便找一个，比如 Petstore 的：
https://petstore.swagger.io/v2/swagger.json
第二步：生成文档
npx @redocly/cli build-docs https://petstore.swagger.io/v2/swagger.json -o my-api-docs.html
第三步：打开看看
直接用浏览器打开 my-api-docs.html，完事。
就这么简单。不需要搭服务器，不需要配数据库，不需要写前端代码。一个命令，文档到手。
进阶玩法：玩转Redoc扩展
Redoc 真正的威力在于它的OpenAPI规范扩展。在你的 OpenAPI 文件里加上这些字段，文档瞬间高大上：
加个Logo：
info:
x-logo:
url:https://your-company.com/logo.png
接口分组：
x-tagGroups:
-name:用户管理
tags:
-用户
-权限
-name:订单系统
tags:
-订单
-支付
多语言代码示例：
paths:
/pets:
get:
x-codeSamples:
-lang:Python
source:|
import requests
r = requests.get('https://api.example.com/pets')
print(r.json())
-lang:Go
source:|
resp, _ := http.Get("https://api.example.com/pets")
defer resp.Body.Close()
这些扩展让你的文档从”能用”变成”好用”，开发者体验直接起飞。
写在最后
Redoc 之所以能成为 GitHub 上最受欢迎的API文档工具，靠的不是花里胡哨，而是把一件事做到了极致。
它不试图做”大而全”的平台，而是专注于把OpenAPI文档渲染得清晰、美观、好用。这种”少即是多”的理念，恰恰是很多工具欠缺的。
如果你还在用 Swagger UI 忍受那”直男审美”的文档界面，不妨试试 Redoc。三分钟迁移，体验提升十倍。
最后，附上项目地址和在线体验：
-
GitHub：https://github.com/redocly/redoc -
在线Demo：https://redocly.github.io/redoc/ -
官方文档：https://redocly.com/docs/redoc/