mcpField
O
openapi

openapi

github.com/oakoss开发21191 次安装12 周前更新
代码仓库

关于 openapi

openapi 是面向 API 设计与实现的 OpenAPI 3.1 规范指南，适用于 API 开发者。内容涵盖规范结构、JSON Schema、类型生成与常见错误。

主要功能

  1. 01定义 HTTP API 契约
  2. 02描述端点、模式与认证
  3. 03支持 JSON Schema 兼容
  4. 04指导类型生成与文档编写
  5. 05列出规范常见错误

适用场景

  1. 01设计 REST API
  2. 02生成 TypeScript、Python 或 Go 客户端类型
  3. 03验证请求与响应负载
  4. 04开展契约优先 API 开发

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/oakoss/agent-skills --skill openapi

安装后在 Claude Code 中输入/openapi确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
code-generation.md
data-types.md
documentation.md
schema-design.md

详细介绍

OpenAPI

概览

OpenAPI Specification（OAS）3.1 是描述 HTTP API 的行业标准。它定义了机器可读的契约，涵盖端点、请求/响应架构、身份验证和错误格式。OpenAPI 3.1 是 JSON Schema Draft 2020-12 的严格超集，因此与 JSON Schema 完全兼容，可用于数据验证和类型生成。

适用场景： 设计 REST API、生成类型化客户端（TypeScript、Python、Go）、制作交互式文档、验证请求/响应负载、采用契约优先的 API 开发方式、配置 API 网关。

不适用场景： GraphQL API（使用 GraphQL 架构）、gRPC 服务（使用 Protocol Buffers）、仅使用 WebSocket 的协议、不会跨越网络边界的内部函数调用。

快速参考

模式元素要点
文档根节点openapi、info、paths顶层必须包含 openapi: '3.1.0'
路径项/resources/{id}路径参数使用花括号
操作get、post、put、delete、patch每个操作都需要 operationId 和 responses
参数in: path|query|header|cookie路径参数始终为 required: true
请求正文requestBody.content以媒体类型为键（application/json）
响应responses.200.content每个操作至少需要一个响应
组件引用$ref: '#/components/schemas/Name'复用架构、参数和响应
架构类型type: string|number|integer|boolean|array|object3.1 中的数组支持 type: ["string", "null"]
组合oneOf、anyOf、allOf建模多态和交集类型
判别器discriminator.propertyName为使用 oneOf/anyOf 的代码生成器提供提示
安全性securitySchemes + 顶层 securityBearer、API key、OAuth2、OpenID Connect
标签操作上的 tags为文档中的操作分组
类型生成openapi-typescript从规范生成零运行时开销的 TypeScript 类型
类型化 fetchopenapi-fetch使用生成的类型构建类型安全的 HTTP 客户端
React Queryopenapi-react-query根据规范生成类型安全的 React Query 钩子
架构优先zod-openapi根据 Zod 架构生成 OpenAPI 文档

常见错误

错误正确做法
在 3.1 中使用 nullable: true使用 type: ["string", "null"]（已移除 3.0 语法）
操作缺少 operationId始终为代码生成设置唯一的 operationId
路径参数未列入 required路径参数始终为必填项（required: true）
到处使用内联架构提取到 components/schemas 并使用 $ref
allOf 中的 required 字段相互冲突合并 required 数组；allOf 会合并这些数组
判别器没有共享属性oneOf/anyOf 中的所有架构都必须包含判别器属性
响应的 description 为空每个响应都需要有意义的 description
使用 type: object，但没有 properties始终定义 properties 或使用 additionalProperties
循环 $ref 链使用延迟解析打破循环，或重构架构
混用 3.0 和 3.1 语法选择一个版本；3.1 移除了 nullable，并将 exclusiveMinimum 改为数字

委派

  • API 设计审查：使用 Task Agent 检查规范的完整性和一致性
  • 类型生成：使用 Explore Agent 查找项目专用的 OpenAPI 工具配置
  • 代码审查：委派给 code-reviewer Agent，检查生成的客户端使用模式

如果可以使用 typescript-patterns 技能，请将高级 TypeScript 类型问题委派给它。

参考资料

评论

支持 Markdown