Back to Details

openapi-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenAPI Design Skill

OpenAPI设计技能

When to Use This Skill

何时使用此技能

Use this skill when:
  • Designing REST APIs - OpenAPI 3.1 for contract-first API design
  • Defining API contracts - Schemas, paths, parameters, responses
  • API best practices - Naming conventions, status codes, versioning
使用此技能的场景：
  • 设计REST API - 采用OpenAPI 3.1进行契约优先的API设计
  • 定义API契约 - 包括模式、路径、参数、响应
  • API最佳实践 - 命名规范、状态码、版本控制

MANDATORY: Documentation-First Approach

强制要求：文档优先方法

Before creating OpenAPI specifications:
  1. Invoke 
    docs-management
    skill     for API design patterns
  2. Verify OpenAPI 3.1 syntax via MCP servers (context7 for latest spec)
  3. Base all guidance on OpenAPI 3.1 specification
在创建OpenAPI规范之前：
  1. 调用
    docs-management
    技能    获取API设计模式
  2. 通过MCP服务器验证OpenAPI 3.1语法（使用context7获取最新规范）
  3. 所有指导均基于OpenAPI 3.1规范

Contract-First Approach

契约优先方法

Why Contract-First?

为什么选择契约优先？

  1. Design before implementation: Think through API before coding
  2. Parallel development: Frontend and backend can work simultaneously
  3. Clear contract: Unambiguous specification for all parties
  4. Auto-generation: Generate clients, servers, documentation
  5. Validation: Validate requests/responses against schema
  1. 先设计再实现：在编码前先梳理清楚API的整体逻辑
  2. 并行开发：前端和后端团队可以同时开展工作
  3. 清晰的契约：为所有参与方提供明确无歧义的规范
  4. 自动生成：可自动生成客户端、服务端代码及文档
  5. 验证机制：依据模式验证请求/响应的合法性

Workflow

工作流程

text
Requirements → OpenAPI Spec → Review → Generate → Implement → Test
     ↑                                                      ↓
     ←←←←←←←←←←←←← Iterate as needed ←←←←←←←←←←←←←←←←←←←←←←
text
需求 → OpenAPI规范 → 评审 → 生成代码 → 开发实现 → 测试
     ↑                                                      ↓
     ←←←←←←←←←←←←← 根据需要迭代优化 ←←←←←←←←←←←←←←←←←←←←←←

OpenAPI 3.1 Structure Overview

OpenAPI 3.1结构概述

yaml
openapi: 3.1.0
info:
  title: API Title
  version: 1.0.0
  description: API description

servers:
  - url: https://api.example.com/v1
    description: Production

tags:
  - name: Orders
    description: Order management

paths:
  # Define endpoints - see paths-definition.md

components:
  schemas: { }
  securitySchemes: { }
  responses: { }
  parameters: { }
For complete template: See paths-definition.md
yaml
openapi: 3.1.0
info:
  title: API Title
  version: 1.0.0
  description: API description

servers:
  - url: https://api.example.com/v1
    description: Production

tags:
  - name: Orders
    description: Order management

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

components:
  schemas: { }
  securitySchemes: { }
  responses: { }
  parameters: { }
完整模板：请查看paths-definition.md

Quick Reference

快速参考

HTTP Methods

HTTP方法

MethodPurposeIdempotent
GETRetrieve resource(s)Yes
POSTCreate resourceNo
PUTReplace resourceYes
PATCHPartial updateNo
DELETERemove resourceYes
方法用途幂等性
GET获取资源是
POST创建资源否
PUT替换资源是
PATCH部分更新资源否
DELETE删除资源是

Common Status Codes

常见状态码

CodeUse For
200Successful GET, PUT, PATCH
201Resource created (POST)
204Successful DELETE
400Malformed request
401Authentication required
404Resource not found
422Validation error
For complete guidance: See design-best-practices.md
状态码使用场景
200成功的GET、PUT、PATCH请求
201资源创建成功（POST请求）
204成功的DELETE请求
400请求格式错误
401需要身份验证
404资源不存在
422验证失败
完整指导：请查看design-best-practices.md

Design Workflow

设计工作流

  1. Understand requirements: What operations are needed?
  2. Design resources: Identify entities and relationships
  3. Define schemas: Create reusable component schemas
  4. Specify endpoints: Define paths and operations
  5. Add security: Configure authentication/authorization
  6. Document examples: Add request/response examples
  7. Validate: Use linting tools (Spectral, etc.)
  8. Review: Get team feedback before implementation
  1. 理解需求：确定需要实现哪些操作？
  2. 设计资源：识别实体及它们之间的关系
  3. 定义模式：创建可复用的组件模式
  4. 指定端点：定义路径和操作
  5. 添加安全机制：配置身份验证/授权
  6. 添加示例文档：补充请求/响应示例
  7. 验证：使用 linting 工具（如Spectral等）
  8. 评审：在开发前获取团队反馈

References

参考资料

Load on-demand based on need:
ReferenceLoad When
paths-definition.mdDefining REST endpoints, operations, parameters
components-definition.mdCreating schemas, responses, security schemes
design-best-practices.mdReviewing naming, status codes, versioning
根据需求按需加载：
参考资料加载场景
paths-definition.md定义REST端点、操作、参数时
components-definition.md创建模式、响应、安全方案时
design-best-practices.md评审命名、状态码、版本控制时

Related Skills (Cross-Plugin)

相关技能（跨插件）

PhaseSkillPluginPurpose
DESIGN
openapi-design
(this skill)		formal-specificationArchitecture research, pattern selection
AUTHORING
openapi-authoring
spec-driven-developmentConcrete YAML file creation
GOVERNANCE
contract-first-design
spec-driven-developmentAPI governance, code generation
Workflow: Design (research patterns) → Author (create YAML) → Govern (enforce contracts)
阶段技能插件用途
设计
openapi-design
（本技能）		formal-specification架构调研、模式选择
编写
openapi-authoring
spec-driven-development创建具体的YAML文件
治理
contract-first-design
spec-driven-developmentAPI治理、代码生成
工作流： 设计（调研模式）→ 编写（创建YAML）→ 治理（执行契约）

External References

外部参考

MCP Research

MCP调研

For current OpenAPI patterns and tools:
text
perplexity: "OpenAPI 3.1 specification" "REST API design patterns"
context7: "openapi" (for official documentation)
ref: "OpenAPI spec examples" "JSON Schema patterns"
如需了解当前OpenAPI模式和工具：
text
perplexity: "OpenAPI 3.1 specification" "REST API design patterns"
context7: "openapi"（用于获取官方文档）
ref: "OpenAPI spec examples" "JSON Schema patterns"

Version History

版本历史

  • v2.0.0 (2026-01-17): Refactored to progressive disclosure pattern
    • Extracted 3 reference files (~500 lines)
    • Hub reduced from 698 to ~130 lines
  • v1.0.0 (2025-12-26): Initial release
Last Updated: 2026-01-17
  • v2.0.0（2026-01-17）：重构为渐进式披露模式
    • 提取3个参考文件（约500行）
    • 核心内容从698行精简至约130行
  • v1.0.0（2025-12-26）：初始发布
最后更新时间： 2026-01-17