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