技能介绍

解决了什么问题

团队把接口定义写进了 OpenAPI 规范文件，但文档往往以静态 Markdown 或过期的导出文件形式存在。读者看不到真实请求参数，联调前也无法确认认证头怎么带、请求体该传什么。这个技能要解决的问题是：把一份 openapi.json 或 openapi.yaml 直接变成一个可交互的 API 文档站点，读者在浏览器里就能发起请求验证接口行为，而不需要额外的后端服务。

它是怎么工作的

核心流程可以拆成几步：

读取规范：从仓库或工作区中定位 OpenAPI 规范文件，解析其中的 paths、components 与安全方案定义。
生成静态站点：基于 Swagger UI 渲染交互式页面，把规范中的路径、参数、请求体与响应模型映射为可视化的接口卡片。
品牌定制：允许注入自定义 CSS 与站点标题，让文档外观与产品视觉体系保持一致，而不是千篇一律的默认布局。
认证预设：支持配置 API Key、Bearer Token 等安全方案的默认值，读者打开页面后无需手工填写即可调用受保护接口。
静态托管：产物是纯静态文件，可以直接发布到 CDN 或对象存储，不依赖运行时服务。
备选渲染：集成了 Redoc，可以在同一份规范上切换渲染方式，适合对移动端阅读或可访问性有额外要求的场景。

适用边界与注意点

这个技能只负责文档的构建与发布，不校验规范本身的正确性。如果 openapi.yaml 里存在错误的 response 定义或缺失的 servers 字段，渲染出的文档会原样暴露这些问题——它忠实反映输入，不做修正。
生成的站点是静态的。如果接口行为依赖服务端实时状态，页面上的请求会打到部署时配置的 server 地址；跨域（CORS）限制由目标服务决定，技能本身无法绕过。
上游 Swagger UI 使用 Scarf 收集匿名安装统计，介意的环境可以在构建时关闭相关追踪。
规范处理逻辑对齐自 swagger-api/swagger-ui 的官方 README，遇到渲染异常时建议先对照上游文档确认参数用法。