openapi-spec

openapi-spec 快速入门

一份 OpenAPI 规范文件 = 文档 + Mock Server + 客户端 SDK + 自动化测试,全自动生成。

这是什么?解决什么问题?

openapi-spec 是 Anthropic 在 anthropics/skills 仓库下提供的一个 Skill,核心用途是教 AI 编程助手如何写符合 OpenAPI 3.x 规范的接口定义文件(YAML/JSON)。
OpenAPI(原名 Swagger)是业界通用的 RESTful API 描述标准。一份 OpenAPI 文件通常长这样:

openapi: 3.0.3<br>
info:<br>
title: 用户管理 API<br>
version: 1.0.0<br>
paths:<br>
/users:<br>
get:<br>
summary: 列出用户<br>
responses:<br>
'200':<br>
description: 成功<br>
content:<br>
application/json:<br>
schema:<br>
$ref: '#/components/schemas/UserList'<br>
```<br>
它解决的问题,是 API 项目中重复造轮子的部分:<br>
- **接口文档**:手写 API 文档容易过时,OpenAPI 文件本身就是"代码化文档",改一处全跟着变。<br>
- **Mock Server**:`prism mock openapi.yaml` 一行命令起一个 mock server,前端不用等后端。<br>
- **客户端 SDK**:`openapi-generator` 一次性生成 Java / TypeScript / Go / Python 等 50+ 语言 SDK。<br>
- **自动化测试**:从 OpenAPI 自动生成接口测试用例,确保实现和文档一致。<br>
- **网关配置**:Kong / Apigee / AWS API Gateway 等都支持从 OpenAPI 导入路由。<br>
这个 Skill 沉淀的能力,就是让 AI 写 OpenAPI 文件时按规范来,避免常见的 JSON Schema 写法错误、复用 component、状态码语义、鉴权描述等问题。<br>
它适合的场景:从零设计新 API、给老 API 补规范文档、Code First 模式(用代码注解自动生成) vs Design First 模式(先写规范再写代码)、API 网关配置自动化。<br>
## 准备工作<br>
1. 一个支持 Skill 加载的 AI 编程助手(Claude Code / Cursor)。<br>
2. 本地装 OpenAPI 工具链:<br>
```bash<br>
npm install -g @redocly/cli<br>
npm install -g @stoplight/prism-cli   # Mock Server<br>
npm install -g @openapitools/openapi-generator-cli   # SDK 生成<br>
```<br>
3. 一个 YAML 编辑器(VS Code + Redocly 扩展 / IntelliJ + OpenAPI 插件)。<br>
4. Clone 仓库:<br>
```bash<br>
git clone https://github.com/anthropics/skills.git<br>
```<br>
5. 软链 Skill:<br>
```bash<br>
ln -s skills/openapi-spec ~/.claude/skills/openapi-spec<br>
```<br>
## 3 步快速上手<br>
### 第 1 步:写第一份 OpenAPI 规范<br>
让 AI 帮你写一个简单的用户管理 API 规范 `openapi.yaml`:<br>
```yaml<br>
openapi: 3.0.3<br>
info:<br>
title: 用户管理 API<br>
version: 1.0.0<br>
description: 用户注册、登录、个人资料管理<br>
servers:<br>
- url: https://api.example.com/v1<br>
paths:<br>
/users:<br>
post:<br>
summary: 创建用户<br>
requestBody:<br>
required: true<br>
content:<br>
application/json:<br>
schema:<br>
$ref: '#/components/schemas/UserCreate'<br>
responses:<br>
'201':<br>
description: 创建成功<br>
content:<br>
application/json:<br>
schema:<br>
$ref: '#/components/schemas/User'<br>
'400':<br>
$ref: '#/components/responses/BadRequest'<br>
'409':<br>
description: 邮箱已存在<br>
/users/{id}:<br>
get:<br>
summary: 获取用户详情<br>
parameters:<br>
- in: path<br>
name: id<br>
required: true<br>
schema:<br>
type: string<br>
responses:<br>
'200':<br>
description: 成功<br>
content:<br>
application/json:<br>
schema:<br>
$ref: '#/components/schemas/User'<br>
'404':<br>
$ref: '#/components/responses/NotFound'<br>
components:<br>
schemas:<br>
User:<br>
type: object<br>
required: [id, email, created_at]<br>
properties:<br>
id:<br>
type: string<br>
format: uuid<br>
email:<br>
type: string<br>
format: email<br>
name:<br>
type: string<br>
created_at:<br>
type: string<br>
format: date-time<br>
UserCreate:<br>
type: object<br>
required: [email, password]<br>
properties:<br>
email:<br>
type: string<br>
format: email<br>
password:<br>
type: string<br>
minLength: 8<br>
responses:<br>
BadRequest:<br>
description: 请求参数错误<br>
NotFound:<br>
description: 资源未找到<br>
```<br>
### 第 2 步:验证安装<br>
```bash<br>
redocly lint openapi.yaml<br>
```<br>
如果输出"Woohoo! Your API description is valid."说明规范语法正确。Skill 会让 AI 主动跑这个 lint 步骤。<br>
### 第 3 步:用 openapi-spec 跑第一个真实任务<br>
**任务 1:起 Mock Server**<br>
```bash<br>
prism mock openapi.yaml<br>
# 启动在 http://localhost:4010<br>
# 前端可以直接调 http://localhost:4010/users 拿到 mock 响应<br>
```<br>
**任务 2:生成 TypeScript 客户端**<br>
```bash<br>
openapi-generator-cli generate \<br>
-i openapi.yaml \<br>
-g typescript-axios \<br>
-o ./generated/typescript-client<br>
```<br>
生成出来的 `generated/typescript-client/` 目录可以直接 import 用。<br>
**任务 3:生成接口测试**<br>
```bash<br>
# 用 schemathesis 自动生成 property-based 测试<br>
pip install schemathesis<br>
schemathesis run openapi.yaml --base-url=http://localhost:3000<br>
```<br>
**任务 4:生成文档站点**<br>
```bash<br>
redocly build-docs openapi.yaml --output=docs/index.html<br>
```<br>
生成静态 HTML 文档,可以挂到 GitHub Pages。<br>
## 常见踩坑<br>
1. **不写 `components/schemas` 复用**。每个 endpoint 重新写一遍 schema,改一处要改 10 处,Skill 强调用 `$ref` 引用。<br>
2. **错误响应不规范化**。400、401、403、404、500 没有统一格式,前端解析要写 5 套代码,Skill 建议用 `components/responses` 统一。<br>
3. **忘记描述鉴权**。API 文档里没写"需要 Bearer token",前端不知道要带 Authorization 头。Skill 强调 `securitySchemes` 必填。<br>
4. **路径设计不 RESTful**。`/getUserById?id=123` 而不是 `GET /users/123`,Skill 会主动纠正。<br>
5. **生成的 SDK 太大**。50 个 endpoint 的 API,生成的 Java SDK 有 30MB,Skill 建议按需生成或用代码分包。<br>
6. **规范和实现脱节**。改了代码忘了改 OpenAPI,文档很快过时,Skill 建议"规范先行"或 CI 自动 diff 检测。<br>
## 初级用法<br>
**用法 1:Design First**。先写 OpenAPI 规范,前后端评审通过,再各自实现。Skill 推荐这种工作流,避免实现到一半发现接口设计有问题。<br>
**用法 2:Code First**。用框架注解自动生成 OpenAPI(比如 FastAPI 的 `app.openapi()`、NestJS 的 `@nestjs/swagger`),改代码自动同步规范。<br>
**用法 3:Mock Server 给前端用**。后端还在写,前端已经能调 Mock 联调,两边并行开发。<br>
## 高级玩法<br>
**玩法 1:API Gateway 自动同步**。把 OpenAPI 推到 AWS API Gateway / Kong / Apigee,自动建路由 + 鉴权 + 限流。<br>
**玩法 2:契约测试**。用 Pact / Dredd / Spectral,自动检测实现是否和 OpenAPI 规范一致,不一致就 CI 失败。<br>
**玩法 3:多语言 SDK 中心化**。把所有 OpenAPI 规范集中到一个仓库,自动生成 Java / Go / TS / Python SDK 发布到内部包管理,业务方按需引入。<br>
## 小技巧<br>
1. **`info.description` 写清楚业务含义**。不是技术细节,是"这个 API 解决什么问题",方便产品/运营理解。<br>
2. **`example` 字段必填**。每个 schema 加 `example`,自动文档里直接看到真实数据格式,不用脑补。<br>
3. **错误响应统一结构**。`{ code: number, message: string, details?: object }`,前端解析逻辑只写一次。<br>
4. **用 Spectral 做 lint**。`spectral lint openapi.yaml` 比 `redocly lint` 规则更严,能查出命名规范、不安全字段等。<br>
5. **OpenAPI 版本锁 3.0.3**。3.1.0 还在普及中,部分工具兼容性差,Skill 建议生产用 3.0.3。<br>
## 常见问题 FAQ<br>
**Q1: 这个 Skill 跟 openapi-spec 有什么关系?必须装吗?**<br>
A: Skill 是给 AI Agent 用的"技能包",能告诉 Agent 怎么按特定规范工作。**不是必须装**——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。<br>

**Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?**<br>
A: openapi-spec 来自 Anthropic,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。<br>

**Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?**<br>
A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。<br>

**Q4: 怎么验证 Skill 装对了?**<br>
A: 在 Agent 中输入"列出已加载的 Skill"或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。<br>

## 参考链接<br>
- [openapi-spec Skill 路径](https://github.com/anthropics/skills/tree/main/skills/openapi-spec)<br>
- [OpenAPI 3.0 规范](https://swagger.io/specification/v3/)<br>
- [Redocly CLI](https://redocly.com/docs/cli/)<br>
- [Prism Mock Server](https://stoplight.io/open-source/prism)<br>
- [openapi-generator](https://openapi-generator.tech/)<br>
- [Spectral Linter](https://stoplight.io/open-source/spectral)