OpenAPI技能Skill openapi

---

name: openapi description: OpenAPI/Swagger 规范、代码生成、文档编写与验证。 allowed-tools: 读取、写入、编辑、Bash、Glob、Grep

OpenAPI 技能

提供创建 OpenAPI 规范和 API 文档的专家级协助。

能力

• 编写 OpenAPI 3.x 规范
• 生成客户端/服务器端代码
• 创建交互式文档
• 验证 API 契约
• 设计请求/响应模式

使用场景

当您需要以下操作时，请调用此技能：

• 为 REST API 编写文档
• 生成 API 客户端
• 验证 API 契约
• 创建交互式文档

规范模式示例

openapi: 3.0.3
info:
  title: 用户 API
  version: 1.0.0

paths:
  /users:
    get:
      summary: 列出用户
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

components:
  schemas:
    User:
      type: object
      required: [id, name, email]
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email

最佳实践

• 使用 $ref 引用可复用的模式
• 为所有响应编写文档
• 包含示例
• 对规范进行版本管理

目标流程

• API 文档编写
• API 设计
• 客户端生成