openapi

mcclowes's avatarfrom mcclowes

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

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 23, 2025
[API Helpers]

When & Why to Use This Skill

This Claude skill acts as a comprehensive OpenAPI Specification (OAS) expert, designed to streamline the lifecycle of API design and documentation. It assists developers in creating, validating, and optimizing OpenAPI files by enforcing structural integrity, managing reusable components, and ensuring adherence to industry best practices for robust and standardized API development.

Use Cases

  • Automated Validation: Instantly identify structural errors, missing required fields, and broken $ref links within complex OpenAPI documents to ensure specification compliance.
  • Efficient API Design: Rapidly draft new endpoints, parameters, and response schemas while maintaining consistent naming conventions and data types across the entire API.
  • Schema Refactoring: Optimize specification files by extracting redundant definitions into reusable components, significantly improving maintainability and reducing file complexity.
  • Security Configuration: Correctly implement and document various security schemes, including OAuth2, Bearer tokens, and API keys, to ensure secure and well-documented API access.
nameopenapi
# IMPORTANTKeep description on ONE line for Claude Code compatibility
descriptionUse 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