⚡

OpenAPI设计Skill openapi-design

此技能用于基于OpenAPI 3.1规范进行合同优先的REST API设计，包括定义API契约、遵循最佳实践和实现设计工作流。关键词：OpenAPI, REST API, 设计, 规范, 合同优先。

架构设计 0 次安装 0 次浏览 更新于 3/11/2026

名称: openapi-design 描述: 基于OpenAPI 3.1规范的合同优先REST API设计 允许工具: Read, Glob, Grep, Write, Edit, mcp__perplexity__search, mcp__context7__resolve-library-id, mcp__context7__query-docs

OpenAPI设计技能

何时使用此技能

在以下情况下使用此技能：

  • 设计REST APIs - 使用OpenAPI 3.1进行合同优先的API设计
  • 定义API契约 - 模式、路径、参数、响应
  • API最佳实践 - 命名约定、状态码、版本控制

强制性：文档优先方法

在创建OpenAPI规范之前：

  1. 调用docs-management技能以获取API设计模式
  2. 通过MCP服务器验证OpenAPI 3.1语法（使用context7获取最新规范）
  3. 所有指导基于OpenAPI 3.1规范

合同优先方法

为什么合同优先？

  1. 实现前设计：在编码前思考API
  2. 并行开发：前端和后端可以同时工作
  3. 清晰契约：对所有方明确的规范
  4. 自动生成：生成客户端、服务器、文档
  5. 验证：根据模式验证请求/响应

工作流

需求 → OpenAPI规范 → 评审 → 生成 → 实现 → 测试
     ↑                                                      ↓
     ←←←←←←←←←←←←← 根据需要迭代 ←←←←←←←←←←←←←←←←←←←←←←

OpenAPI 3.1结构概述

openapi: 3.1.0
info:
  title: API标题
  version: 1.0.0
  description: API描述

servers:
  - url: https://api.example.com/v1
    description: 生产环境

tags:
  - name: Orders
    description: 订单管理

paths:
  # 定义端点 - 参见paths-definition.md

components:
  schemas: { }
  securitySchemes: { }
  responses: { }
  parameters: { }

完整模板：参见paths-definition.md

快速参考

HTTP方法

方法 目的 幂等性
GET 检索资源 是
POST 创建资源 否
PUT 替换资源 是
PATCH 部分更新 否
DELETE 删除资源 是

常见状态码

代码 用途
200 成功的GET、PUT、PATCH
201 资源创建（POST）
204 成功的DELETE
400 错误请求
401 需要认证
404 资源未找到
422 验证错误

完整指导：参见design-best-practices.md

设计工作流

  1. 理解需求：需要什么操作？
  2. 设计资源：识别实体和关系
  3. 定义模式：创建可重用的组件模式
  4. 指定端点：定义路径和操作
  5. 添加安全：配置认证/授权
  6. 文档示例：添加请求/响应示例
  7. 验证：使用linting工具（如Spectral等）
  8. 评审：在实现前获取团队反馈

参考

根据需要加载：

参考 加载时机
paths-definition.md 定义REST端点、操作、参数
components-definition.md 创建模式、响应、安全方案
design-best-practices.md 评审命名、状态码、版本控制

相关技能（跨插件）

阶段 技能 插件 目的
设计 openapi-design（此技能） formal-specification 架构研究、模式选择
编写 openapi-authoring spec-driven-development 具体的YAML文件创建
治理 contract-first-design spec-driven-development API治理、代码生成

工作流： 设计（研究模式） → 编写（创建YAML） → 治理（执行契约）

外部参考

MCP研究

对于当前的OpenAPI模式和工具：

perplexity: "OpenAPI 3.1 specification" "REST API design patterns"
context7: "openapi"（用于官方文档）
ref: "OpenAPI规范示例" "JSON模式模式"

版本历史

  • v2.0.0 (2026-01-17)：重构为渐进披露模式
    • 提取了3个参考文件（约500行）
    • 中心从698行减少到约130行
  • v1.0.0 (2025-12-26)：初始发布

最后更新： 2026-01-17