mcpField
O
openapi-spec-generation

openapi-spec-generation

github.com/wshobson开发41.9k16.6k 次安装2 周前更新
代码仓库

关于 openapi-spec-generation

用于创建、维护和验证 OpenAPI 3.1 规范的技能，面向 API 设计者和开发者，涵盖设计优先、代码优先及混合工作方式。

主要功能

  1. 01OpenAPI 3.1 结构与模式
  2. 02设计优先、代码优先及混合流程
  3. 03规范验证与实现检查
  4. 04可复用模式、示例和错误文档
  5. 05SDK 生成与 API 门户指引

适用场景

  1. 01在实现前起草 API 契约
  2. 02根据现有代码生成规范
  3. 03检查 API 实现是否符合规范
  4. 04为 SDK 生成准备规范

安装

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

$npx skills add https://github.com/wshobson/agents --skill openapi-spec-generation

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

附带文件references/code-first-and-tooling.mdreferences/details.md

详细介绍

OpenAPI 规范生成

为 RESTful API 创建、维护和验证 OpenAPI 3.1 规范的全面模式。

何时使用本技能

  • 从零开始创建 API 文档
  • 从现有代码生成 OpenAPI 规范
  • 设计 API 契约（设计优先方法）
  • 根据规范验证 API 实现
  • 从规范生成客户端 SDK
  • 搭建 API 文档门户

核心概念

1. OpenAPI 3.1 结构
openapi: 3.1.0
info:
  title: API Title
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /resources:
    get: ...
components:
  schemas: ...
  securitySchemes: ...
2. 设计方法
方法描述最适合
设计优先先编写规范再编写代码新 API、契约
代码优先从代码生成规范现有 API
混合为代码添加注解，生成规范演进中的 API

模板和详细示例

完整的模板库和详细的示例位于 references/details.md。当你需要具体模板时，请阅读该文件。

最佳实践

应该做的
  • 使用 $ref - 复用 schema、参数、响应
  • 添加示例 - 真实世界的值有助于使用者
  • 记录错误 - 所有可能的错误码
  • 为 API 添加版本 - 在 URL 或请求头中
  • 使用语义化版本 - 用于规范变更
不应该做的
  • 不要使用笼统的描述 - 要具体
  • 不要跳过安全 - 定义所有方案
  • 不要忘记 nullable - 对 null 要明确
  • 不要混用风格 - 始终保持命名一致
  • 不要硬编码 URL - 使用服务器变量

评论

支持 Markdown