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
info:
  title: 用户管理 API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 列出用户
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

它解决的问题,是 API 项目中重复造轮子的部分:

• 接口文档:手写 API 文档容易过时,OpenAPI 文件本身就是”代码化文档”,改一处全跟着变。
• Mock Server:prism mock openapi.yaml 一行命令起一个 mock server,前端不用等后端。
• 客户端 SDK:openapi-generator 一次性生成 Java / TypeScript / Go / Python 等 50+ 语言 SDK。
• 自动化测试:从 OpenAPI 自动生成接口测试用例,确保实现和文档一致。
• 网关配置:Kong / Apigee / AWS API Gateway 等都支持从 OpenAPI 导入路由。

这个 Skill 沉淀的能力,就是让 AI 写 OpenAPI 文件时按规范来,避免常见的 JSON Schema 写法错误、复用 component、状态码语义、鉴权描述等问题。

它适合的场景:从零设计新 API、给老 API 补规范文档、Code First 模式(用代码注解自动生成) vs Design First 模式(先写规范再写代码)、API 网关配置自动化。

准备工作

1. 一个支持 Skill 加载的 AI 编程助手(Claude Code / Cursor)。
2. 本地装 OpenAPI 工具链:

   npm install -g @redocly/cli
   npm install -g @stoplight/prism-cli   # Mock Server
   npm install -g @openapitools/openapi-generator-cli   # SDK 生成
   

3. 一个 YAML 编辑器(VS Code + Redocly 扩展 / IntelliJ + OpenAPI 插件)。
4. Clone 仓库:

   git clone https://github.com/anthropics/skills.git
   

5. 软链 Skill:

   ln -s skills/openapi-spec ~/.claude/skills/openapi-spec
   

3 步快速上手

第 1 步:写第一份 OpenAPI 规范

让 AI 帮你写一个简单的用户管理 API 规范 openapi.yaml:

openapi: 3.0.3
info:
  title: 用户管理 API
  version: 1.0.0
  description: 用户注册、登录、个人资料管理
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    post:
      summary: 创建用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: 邮箱已存在
  /users/{id}:
    get:
      summary: 获取用户详情
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    User:
      type: object
      required: [id, email, created_at]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        created_at:
          type: string
          format: date-time
    UserCreate:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 8
  responses:
    BadRequest:
      description: 请求参数错误
    NotFound:
      description: 资源未找到

第 2 步:验证安装

redocly lint openapi.yaml

如果输出”Woohoo! Your API description is valid.”说明规范语法正确。Skill 会让 AI 主动跑这个 lint 步骤。

第 3 步:用 openapi-spec 跑第一个真实任务

任务 1:起 Mock Server

prism mock openapi.yaml
# 启动在 http://localhost:4010
# 前端可以直接调 http://localhost:4010/users 拿到 mock 响应

任务 2:生成 TypeScript 客户端

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./generated/typescript-client

生成出来的 generated/typescript-client/ 目录可以直接 import 用。

任务 3:生成接口测试

# 用 schemathesis 自动生成 property-based 测试
pip install schemathesis
schemathesis run openapi.yaml --base-url=http://localhost:3000

任务 4:生成文档站点

redocly build-docs openapi.yaml --output=docs/index.html

生成静态 HTML 文档,可以挂到 GitHub Pages。

常见踩坑

1. 不写 components/schemas 复用。每个 endpoint 重新写一遍 schema,改一处要改 10 处,Skill 强调用 $ref 引用。
2. 错误响应不规范化。400、401、403、404、500 没有统一格式,前端解析要写 5 套代码,Skill 建议用 components/responses 统一。
3. 忘记描述鉴权。API 文档里没写”需要 Bearer token”,前端不知道要带 Authorization 头。Skill 强调 securitySchemes 必填。
4. 路径设计不 RESTful。/getUserById?id=123 而不是 GET /users/123,Skill 会主动纠正。
5. 生成的 SDK 太大。50 个 endpoint 的 API,生成的 Java SDK 有 30MB,Skill 建议按需生成或用代码分包。
6. 规范和实现脱节。改了代码忘了改 OpenAPI,文档很快过时,Skill 建议”规范先行”或 CI 自动 diff 检测。

初级用法

用法 1:Design First。先写 OpenAPI 规范,前后端评审通过,再各自实现。Skill 推荐这种工作流,避免实现到一半发现接口设计有问题。

用法 2:Code First。用框架注解自动生成 OpenAPI(比如 FastAPI 的 app.openapi()、NestJS 的 @nestjs/swagger),改代码自动同步规范。

用法 3:Mock Server 给前端用。后端还在写,前端已经能调 Mock 联调,两边并行开发。

高级玩法

玩法 1:API Gateway 自动同步。把 OpenAPI 推到 AWS API Gateway / Kong / Apigee,自动建路由 + 鉴权 + 限流。

玩法 2:契约测试。用 Pact / Dredd / Spectral,自动检测实现是否和 OpenAPI 规范一致,不一致就 CI 失败。

玩法 3:多语言 SDK 中心化。把所有 OpenAPI 规范集中到一个仓库,自动生成 Java / Go / TS / Python SDK 发布到内部包管理,业务方按需引入。

小技巧

1. info.description 写清楚业务含义。不是技术细节,是”这个 API 解决什么问题”,方便产品/运营理解。
2. example 字段必填。每个 schema 加 example,自动文档里直接看到真实数据格式,不用脑补。
3. 错误响应统一结构。{ code: number, message: string, details?: object },前端解析逻辑只写一次。
4. 用 Spectral 做 lint。spectral lint openapi.yaml 比 redocly lint 规则更严,能查出命名规范、不安全字段等。
5. OpenAPI 版本锁 3.0.3。3.1.0 还在普及中,部分工具兼容性差,Skill 建议生产用 3.0.3。

常见问题 FAQ

Q1: 这个 Skill 跟 openapi-spec 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: openapi-spec 来自 Anthropic,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

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

Q4: 怎么验证 Skill 装对了?

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

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 openapi-spec 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

进阶学习建议

如果想进一步用好 openapi-spec,建议按以下路径学习:

第 1 周:熟练使用

• 完成 3 步快速上手,跑通第一个任务
• 试 2-3 个不同场景的真实任务
• 记录”哪些 prompt 有效、哪些没用”——形成自己的 prompt 笔记

第 2 周:理解机制

• 阅读 Skill 的官方文档(README、SKILL.md)
• 了解 Skill 的”触发关键词”和”输出格式”
• 学习”如何用更具体的描述触发 Skill”

第 3-4 周:组合使用

• 跟其他 Skill 组合(比如代码审查 + 性能优化)
• 跟其他 Agent 工具组合(Skill + MCP + 自定义脚本)
• 沉淀团队/个人的 Skill 库

长期:贡献社区

• 把自定义的 Skill 开源到 GitHub
• 提 PR 改进现有 Skill
• 写使用心得分享到 CSDN/掘金/知乎

推荐资源:

• 官方文档:https://github.com/anthropics/skills
• 官方仓库 README 里的 Examples
• 社区最佳实践:Anthropic 官方博客 https://www.anthropic.com/blog
• 国内社区:CSDN AI 板块、掘金 AI 板块

避免的坑:

• 不要装太多 Skill(超过 10 个会拖慢 Agent)
• 不要把 Skill 装在不兼容的 Agent 上
• 不要直接复制 Skill 默认 prompt——要根据项目调整
• 定期 review Skill 库的实用性,清理不用的

参考链接

• openapi-spec Skill 路径:https://github.com/anthropics/skills/tree/main/skills/openapi-spec
• OpenAPI 3.0 规范:https://swagger.io/specification/v3/
• Redocly CLI:https://redocly.com/docs/cli/
• Prism Mock Server:https://stoplight.io/open-source/prism
• openapi-generator:https://openapi-generator.tech/
• Spectral Linter:https://stoplight.io/open-source/spectral

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。