Generate High-Quality OpenAPI Specifications

This skill is expert in OpenAPI specification writing, API documentation, and REST API design patterns, with deep knowledge of OpenAPI 3.0+ standards and developer-friendly specs that serve both human readers and automated tooling. It structures specifications with a logical hierarchy - kebab-case paths, camelCase properties, tag-grouped endpoints, reusable schemas in the components section, clearly defined security schemes, and a servers array for production and staging environments. It documents every endpoint completely: path and query parameters with type/format/example, every possible response code (200 with content examples, 404, 403) each mapped to a schema reference, and per-endpoint security requirements. It defines reusable component schemas with validation rules (required fields, maxLength, format like uuid/email/date-time, enum values, readOnly markers) and a standard Error schema, security scheme definitions (bearer JWT with a description of how to obtain a token), and reusable parameter definitions like paginated limit/offset with min/max/default constraints.

Use this skill when writing or reviewing an OpenAPI spec that needs to serve as the actual source of truth for both documentation and tooling - not a rough sketch of endpoints. Its documentation best practices call for providing business-logic context beyond technical details, extensive realistic examples for every request/response/parameter, complete error-scenario documentation with specific codes, semantic versioning with breaking-change notes, and rate-limiting documentation. It covers advanced extensions - custom x-code-samples blocks embedding curl and JavaScript examples directly in the spec, and webhook documentation for event-driven APIs - plus a validation and QA checklist: run OpenAPI validators (Spectral, swagger-codegen) in CI/CD, test generated code samples against the real API, validate examples match schema definitions, confirm all referenced components exist, and verify rendering in multiple tools (Swagger UI, Redoc, Postman). It is not a guide for informal or partial API documentation - the standard here is a spec complete enough to drive code generation and automated validation.

paths:
  /users/{userId}:
    get:
      tags:
        - Users
      summary: Retrieve user details
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
            example: "123e4567-e89b-12d3-a456-426614174000"
      responses:
        '200':
          description: User details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []

Given an API's resources, the skill produces a complete OpenAPI 3.0.3 document: an info block with contact/license/rate-limit details, a servers array, fully documented paths like the one above with every response code and example, reusable component schemas with validation constraints, security scheme definitions, reusable pagination parameters, x-code-samples extensions with curl/JavaScript examples, and webhook definitions for event payloads.

API developers and technical writers producing OpenAPI specs that need to be genuinely complete - driving code generation, client SDKs, and interactive documentation tools, not just describing endpoints loosely. It suits teams that validate specs in CI/CD with tools like Spectral, want embedded code samples for multiple languages, and need documentation that renders correctly across Swagger UI, Redoc, and Postman.