默认中文文档 | English
swagger-doc-skill 是一个帮助 Codex 阅读 Swagger/OpenAPI 文档的 skill。你可以给它一个 Swagger UI、Knife4j、Redoc、FastAPI docs、OpenAPI JSON/YAML 地址，或者本地 spec 文件，它会帮你查询模块、查找接口、理解请求/响应字段、查看类型定义，并导出完整接口文档。
它适合用在这种场景：你不想自己在很大的 Swagger 页面里来回搜索，而是希望直接问 Codex：“我要对接登录功能，应该用哪个接口？”
- 自动发现 Swagger UI、Knife4j、Redoc、FastAPI docs 和
swagger-resources背后的真实 OpenAPI 文档。 - 查询模块/tag、接口列表和接口摘要。
- 按功能意图查接口，支持常见中英文关键词，例如登录/auth/token、任务/run/job、设备/device/instrument。
- 查看完整请求参数、请求体、响应结构和可复用 DTO/schema 类型定义。
- 生成接口对接说明，包括请求 URL、鉴权说明、
curl示例和 JavaScriptfetch示例。 - 导出完整 API 文档为 Markdown 或 JSON。
- 在接口文档服务不稳定时使用本地缓存。
- Codex 支持自定义 skills。
- Codex 运行环境里可以使用 Node.js。
- 不需要 Python 环境。
- 普通 Swagger UI 或 OpenAPI JSON 场景不需要执行
npm install。 - 直接解析 YAML spec 是可选能力，可能需要
yamlnpm 包。如果 YAML 解析不可用，建议使用 OpenAPI JSON 地址或导出的 JSON 文件。
在 Codex 里说：
请从 GitHub 安装这个 skill：
https://github.com/Jason-chen-coder/swagger-doc-skill/tree/main/swagger-doc-skill
安装完成后，重启 Codex，让新 skill 生效。
把仓库里的 swagger-doc-skill/ 文件夹复制到你的 Codex skills 目录：
~/.codex/skills/swagger-doc-skill
然后重启 Codex。
直接在聊天里使用即可。大多数情况下，你不需要手动运行脚本。
User:
这个 Swagger 地址是
http://host/doc#/，帮我看一下有哪些模块。Codex:
我会使用
swagger-doc-skill读取文档，并返回模块/tag 列表。
User:
我要对接登录功能，Swagger 地址是
http://host/doc#/，帮我找对应接口。Codex:
我会用登录、auth、token 等关键词查找候选接口。如果只命中一个明确接口，会直接给出对接说明；如果命中多个接口，会先让你选择。
User:
帮我看一下
POST /api/user/login怎么请求，响应字段是什么。Codex:
我会返回 method、URL、鉴权方式、请求头、path/query/body 参数、响应结构和调用示例。
User:
把这个 Swagger 的完整接口文档导出成 Markdown 文件，文件名叫
swagger-api.md。Codex:
我会把模块、接口、请求/响应说明和可复用类型定义导出到 Markdown 文件。
User:
帮我查一下登录接口怎么对接。
Codex:
请提供 Swagger 文档地址、OpenAPI JSON/YAML 地址，或
swagger.config.json配置文件路径。
swagger-doc-skill 不会把某个会话里的 Swagger 地址保存成全局默认地址。
- A 会话里确认的 Swagger 地址，只在 A 会话里作为后续问题的上下文。
- B 会话里可以确认另一个 Swagger 地址，不会自动继承 A 会话的地址。
- 如果同一个会话里出现多个 Swagger 地址，Codex 应该先确认你要查哪一个。
- 每次回答接口查询结果时，Codex 应该明确说明当前使用的 Swagger 文档来源。
- 不建议把业务项目地址写进 skill 目录里的共享配置文件。
如果你经常查询同一个接口文档，可以基于 skill 目录里的 swagger.config.example.json 创建项目级 swagger.config.json。它可以保存文档地址、鉴权 token、自定义请求头和缓存路径。
配置文件需要显式指定使用，例如在聊天里说：
这个项目使用
./swagger.config.json作为 Swagger 配置。
请把私有 token 留在本地配置文件里，不要提交 swagger.config.json。脚本不会再自动读取 skill 目录里的共享 swagger.config.json，这样可以避免多会话或多项目串用同一个 Swagger 地址。
中文请求默认用中文回答，并尽量使用这些简洁结构：
- 模块列表
- 接口列表
- 请求说明
- 响应说明
- 类型定义
- 对接示例
这个 skill 不会编造接口。所有回答都应该来自你提供或配置的 Swagger/OpenAPI 文档。