openapi
使用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, andpathsorwebhooksat 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
operationIdper operation - Use CommonMark in
descriptionfields - Concrete paths match before templated
- Document all response codes