swagger-doc-skill

从 Swagger UI 找到真实 spec，按任务提取 endpoint 与 schema，生成可核对的请求示例。

查看 GitHub

了解工作流

一次真实查询

你说要接登录，它先把依据摆出来

这段输出来自仓库的 OpenAPI 回归夹具，不是为了首页临时编的一组字段。

USER / INPUT

local / codex

我要对接登录功能。帮我从这份 Swagger 里确认接口、鉴权和响应字段。

AI / DOCUMENT OUTPUT

fixture verified

当前来源：OpenAPI 3.0 · Example Response API

Integration Guide

POST /login

Request URL: POST https://api.example.com/v1/login

Summary: Login

Auth

none documented for this endpoint

Request

Request body: required yes

Content-Type: application/json · type object

username string · required · Login name
password string · required · format password

Response

Status: 200 OK

Content-Type: application/json · type object

code integer · example 200
message string · example "Success"
success boolean · example true
data object
data.token string · example "abc"
data.expiresIn integer · example 3600

cURL

curl --request POST 'https://api.example.com/v1/login' \
  --header 'Content-Type: application/json' \
  --data '{"username":"string","password":"string"}'

fetch

const response = await fetch("https://api.example.com/v1/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    username: "string",
    password: "string"
  })
});

const data = await response.json();

01 / source first

Swagger UI 只是入口

页面能打开，不代表模型已经拿到协议。这个 skill 先确认来源，再谈接口。

01

接收文档入口

Swagger UI、Knife4j、Redoc、FastAPI docs，或直接 JSON / YAML。
02

发现真实 spec

检查页面配置、embedded swaggerDoc、常见路径与 swagger-resources。
03

确认 endpoint

按 tag、method、path 或中英文关键词筛选；多候选时先让人选择。
04

展开接口契约

解析 URL、security、参数、request body、response schema 和本地引用。

02 / ask less, know more

按任务控制上下文

不必每次吞下整份 OpenAPI。先选问题，再展开刚好够用的协议细节。

建立系统地图

先看有哪些模块和 tag

--mode modules

返回模块、endpoint 数量与 method 分布，不展开不相关的请求体。

缩小候选范围

按功能、tag、method 或 path 找接口

--mode endpoints --search "登录"

命中多个时保留 method、path、tag 和 summary，等待确认。

精确到 method + path

查看一个接口怎样请求与响应

--mode endpoint --path "/profile" --method GET

展开参数位置、请求体、状态码和响应字段。

还原可复用类型

单独查看 DTO、schema 与 required 字段

--mode types --type UserProfile

支持本地 $ref、旧式 originalRef 与递归深度保护。

交给开发任务

生成可核对的接口对接说明

--mode integration --path "/login" --method POST

包含请求 URL、鉴权、schema、curl 与 JavaScript fetch。

沉淀完整产物

导出 Markdown 或结构化 JSON

--mode document --output swagger-api.md

按模块汇总 endpoint，再附逐接口详情和类型定义。

03 / one spec, two answers

鉴权不能靠常识补

下面来自仓库回归夹具。同一份 spec，两个接口给出相反的鉴权结论。

POST /login

接口级 security: [] 覆盖全局设置。

Auth: none documented
Body: username + password required
Response: example 还原 data.token

GET /profile

继承全局 BearerAuth，并解析旧式引用。

Header: Authorization: Bearer <token>
Schema: originalRef: UserProfile
Fields: id required · name optional

04 / stop conditions

该停的时候，先停下来

少生成一点，也不要把来源不明的猜测写进业务代码。

01没有文档来源
索要 URL、本地 spec 或显式配置，不猜地址。
02候选不唯一
列出 method、path、tag 和 summary，请用户选择。
03文档需要登录
使用安全 header 或导出的 spec，不绕过认证。
04schema 含义不明
保留原名和未知项，不补写业务语义。

ready when your spec is

让 Codex 先确认接口，再开始写代码。

查看源码