openapi

mcclowes 的头像作者 mcclowes

使用OpenAPI规范文件验证、创建/修改路径和模式、检查引用,并强制执行最佳实践时使用

📖 中文导读:使用OpenAPI规范文件验证、创建/修改路径和模式、检查引用,并强制执行最佳实践时使用 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: openapi

IMPORTANT: Keep description on ONE line for Claude Code compatibility

prettier-ignore

description: Use when working with OpenAPI Specification files to validate, create/modify paths and schemas, check references, and enforce best practices

OpenAPI Specification Expert

Quick Start

openapi: 3.1.0
info:
  title: API Name
  version: 1.0.0
paths:
  /users/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id: { type: string }
        email: { type: string, format: email }

Core Principles

  • Required Structure: openapi, info, and paths or webhooks at root
  • Reuse Components: Define schemas/parameters/responses in components/, reference with $ref
  • Match Parameters: Path parameters like {id} MUST have parameter definitions
  • Case Sensitive: All field names follow JSON Schema case sensitivity

Common Operations

Validate structure, create/modify endpoints with operations and parameters, manage reusable schemas with JSON Schema validation, configure security schemes (apiKey/http/oauth2), handle $ref paths, check operation IDs

Key Rules

  • Unique operationId per operation
  • Use CommonMark in description fields
  • Concrete paths match before templated
  • Document all response codes