Claude Skill

api-specs-openapi

OpenAPI 3.1 specification, schema design, code generation

LLM Mart · 0 points · 3 views 0 listing impressions 0 install-command copies
Download agents-inc-skills-dist_plugins_api-specs-openapi_skills_api-specs-openapi-707467a.zip · 16 KB

Install

skills CLI npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/api-specs-openapi/skills/api-specs-openapi
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
Git git clone https://github.com/agents-inc/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

OpenAPI Specification Patterns

Quick Guide: Use OpenAPI 3.1 for API contracts. 3.1 is a superset of JSON Schema Draft 2020-12 -- use type: ["string", "null"] instead of nullable: true. Define all reusable schemas in components/schemas and reference with $ref. Always include operationId on every operation (it becomes the client method name). Use openapi-typescript to generate zero-runtime TypeScript types and openapi-fetch for a 6kb type-safe fetch client.


<critical_requirements>

CRITICAL: Before Using This Skill

(You MUST use OpenAPI 3.1 syntax -- type: ["string", "null"] NOT the 3.0 nullable: true keyword)

(You MUST define reusable schemas in components/schemas and reference with $ref -- NO inline schema duplication)

(You MUST include operationId on every path operation -- it becomes the generated client method name)

(You MUST use openapi-typescript for type generation and import types with import type -- types are zero-runtime)

</critical_requirements>


Auto-detection: OpenAPI, openapi, swagger, openapi-typescript, openapi-fetch, createClient, paths, components, schemas, operationId, $ref, discriminator, oneOf, allOf, anyOf, openapi: "3.1", spec-first, API contract, API specification, code generation, schema design

When to use:

  • Defining API contracts before or alongside implementation (spec-first or code-first)
  • Generating TypeScript types from an existing OpenAPI spec
  • Building type-safe API clients with automatic request/response validation
  • Documenting REST APIs for external or internal consumers
  • Designing reusable schema components with $ref composition

When NOT to use:

  • Internal-only endpoints with no external consumers and no documentation needs
  • GraphQL APIs (use GraphQL schema tooling instead)
  • Simple scripts or prototypes where formal contracts add overhead

Key patterns covered:

  • OpenAPI 3.1 spec structure (info, paths, components, servers)
  • Schema design with JSON Schema Draft 2020-12 alignment
  • $ref composition, oneOf/allOf/anyOf, discriminators
  • Path operations with parameters, request bodies, and responses
  • TypeScript type generation with openapi-typescript v7
  • Type-safe fetch client with openapi-fetch
  • Spec-first vs code-first decision framework

Detailed Resources:




<decision_framework>

Decision Framework

Spec-First vs Code-First

Is this a public or multi-consumer API?
|-- YES --> Spec-first (design contract, get feedback, then implement)
+-- NO  --> Is this a rapid prototype?
    |-- YES --> Code-first (generate spec from annotations)
    +-- NO  --> Does your framework generate OpenAPI from code?
        |-- YES --> Code-first (framework handles spec generation)
        +-- NO  --> Spec-first (write the YAML, generate types)

Schema Composition

Need to share fields across schemas?
|-- YES --> allOf with a base $ref schema
+-- NO  --> Need polymorphism (multiple possible shapes)?
    |-- YES --> oneOf with discriminator
    +-- NO  --> Need to combine constraints?
        |-- YES --> allOf (all must match)
        +-- NO  --> Simple schema with $ref for nested objects

Type Generation Tooling

Need Tool When
TypeScript types from spec openapi-typescript v7 Always -- zero-runtime type generation
Type-safe fetch client openapi-fetch Frontend or service-to-service calls
Full SDK generation @hey-api/openapi-ts Need Zod schemas, query hooks, or full SDKs
Spec validation/linting Redocly CLI CI pipeline, pre-commit checks

</decision_framework>


<red_flags>

RED FLAGS

High Priority:

  • Using nullable: true -- removed in OpenAPI 3.1, use type: ["string", "null"]
  • Duplicating schemas inline instead of using $ref to components/schemas -- creates drift
  • Missing operationId on operations -- generated clients get ugly auto-generated names
  • Manually maintaining TypeScript interfaces that mirror the spec -- use openapi-typescript to generate them
  • Using openapi: "3.0.x" when 3.1 is available -- misses JSON Schema alignment

Medium Priority:

  • Defining error responses without a shared Error schema -- inconsistent error shapes across endpoints
  • Missing required array on object schemas -- all properties become optional by default
  • Using type: object without additionalProperties: false when extra fields should be rejected
  • Not documenting 4xx/5xx responses -- consumers don't know what error shapes to expect

Gotchas & Edge Cases:

  • $ref siblings are ignored in 3.0 but allowed in 3.1 -- description next to $ref now works in 3.1
  • exclusiveMinimum/exclusiveMaximum changed from boolean (3.0) to number (3.1) -- exclusiveMinimum: 0 means "greater than 0"
  • discriminator does not affect validation -- it's a hint for code generators, not a constraint
  • discriminator.propertyName must be a required string property at the same schema level
  • Inline schemas inside discriminator oneOf are not considered -- only $ref entries work
  • openapi-typescript generates .d.ts files -- these are type-only, no runtime code
  • openapi-fetch data is only present for 2xx responses, error for 4xx/5xx -- always check which is defined
  • Response bodies are consumed once -- clone the response if middleware needs to read it and pass it through
  • openapi-typescript v7 uses redocly.yaml for multi-schema config -- globbing is deprecated

</red_flags>


<critical_reminders>

CRITICAL REMINDERS

(You MUST use OpenAPI 3.1 syntax -- type: ["string", "null"] NOT the 3.0 nullable: true keyword)

(You MUST define reusable schemas in components/schemas and reference with $ref -- NO inline schema duplication)

(You MUST include operationId on every path operation -- it becomes the generated client method name)

(You MUST use openapi-typescript for type generation and import types with import type -- types are zero-runtime)

Failure to follow these rules will cause schema drift, broken codegen, and type mismatches between spec and implementation.

</critical_reminders>

Files (skills)
  • examples
    • codegen.md 8 KB
      Loading…
    • core.md 14.8 KB
      Loading…
    • validation.md 7.5 KB
      Loading…
  • reference.md 6.3 KB
    Loading…
  • SKILL.md 13.1 KB
    ---
    name: api-specs-openapi
    description: OpenAPI 3.1 specification, schema design, code generation
    ---
    
    # OpenAPI Specification Patterns
    
    > **Quick Guide:** Use OpenAPI 3.1 for API contracts. 3.1 is a superset of JSON Schema Draft 2020-12 -- use `type: ["string", "null"]` instead of `nullable: true`. Define all reusable schemas in `components/schemas` and reference with `$ref`. Always include `operationId` on every operation (it becomes the client method name). Use `openapi-typescript` to generate zero-runtime TypeScript types and `openapi-fetch` for a 6kb type-safe fetch client.
    
    ---
    
    <critical_requirements>
    
    ## CRITICAL: Before Using This Skill
    
    **(You MUST use OpenAPI 3.1 syntax -- `type: ["string", "null"]` NOT the 3.0 `nullable: true` keyword)**
    
    **(You MUST define reusable schemas in `components/schemas` and reference with `$ref` -- NO inline schema duplication)**
    
    **(You MUST include `operationId` on every path operation -- it becomes the generated client method name)**
    
    **(You MUST use `openapi-typescript` for type generation and import types with `import type` -- types are zero-runtime)**
    
    </critical_requirements>
    
    ---
    
    **Auto-detection:** OpenAPI, openapi, swagger, openapi-typescript, openapi-fetch, createClient, paths, components, schemas, operationId, $ref, discriminator, oneOf, allOf, anyOf, openapi: "3.1", spec-first, API contract, API specification, code generation, schema design
    
    **When to use:**
    
    - Defining API contracts before or alongside implementation (spec-first or code-first)
    - Generating TypeScript types from an existing OpenAPI spec
    - Building type-safe API clients with automatic request/response validation
    - Documenting REST APIs for external or internal consumers
    - Designing reusable schema components with `$ref` composition
    
    **When NOT to use:**
    
    - Internal-only endpoints with no external consumers and no documentation needs
    - GraphQL APIs (use GraphQL schema tooling instead)
    - Simple scripts or prototypes where formal contracts add overhead
    
    **Key patterns covered:**
    
    - OpenAPI 3.1 spec structure (info, paths, components, servers)
    - Schema design with JSON Schema Draft 2020-12 alignment
    - `$ref` composition, `oneOf`/`allOf`/`anyOf`, discriminators
    - Path operations with parameters, request bodies, and responses
    - TypeScript type generation with `openapi-typescript` v7
    - Type-safe fetch client with `openapi-fetch`
    - Spec-first vs code-first decision framework
    
    **Detailed Resources:**
    
    - [examples/core.md](examples/core.md) - Spec structure, schemas, paths, operations, `$ref` composition
    - [examples/codegen.md](examples/codegen.md) - TypeScript type generation, `openapi-fetch` client
    - [examples/validation.md](examples/validation.md) - Request/response validation, middleware patterns
    - [reference.md](reference.md) - Decision frameworks, anti-patterns, quick-lookup tables
    
    ---
    
    <philosophy>
    
    ## Philosophy
    
    **The spec IS the contract.** An OpenAPI document is the single source of truth for your API's shape. Types, documentation, client SDKs, and server validation are all derived from it -- never maintained separately.
    
    **OpenAPI 3.1 aligns with JSON Schema Draft 2020-12.** This means any valid JSON Schema is a valid OpenAPI schema. Use `type` arrays for nullable (`["string", "null"]`), `if/then/else` for conditional schemas, and standard JSON Schema vocabulary.
    
    **Spec-first (design-first) is recommended** for stable, multi-consumer APIs. Define the contract first, get feedback from consumers via mocks, then implement. Code-first works for rapid prototypes where the spec is generated from annotations.
    
    **Use spec-first when:**
    
    - Multiple teams consume the API
    - API is public or has external consumers
    - Contract stability matters (breaking changes are expensive)
    - You want mocks and docs before writing any code
    
    **Use code-first when:**
    
    - Rapid prototyping where the spec is generated from code annotations
    - Single-team internal APIs where the implementation IS the contract
    - Framework provides first-class OpenAPI generation from code annotations
    
    </philosophy>
    
    ---
    
    <patterns>
    
    ## Core Patterns
    
    ### Pattern 1: Spec Structure
    
    Every OpenAPI 3.1 document has four required top-level fields: `openapi`, `info`, `paths` (or `webhooks`), and implicitly `components` for reusable schemas.
    
    ```yaml
    openapi: "3.1.0"
    info:
      title: Jobs API
      version: "1.0.0"
      description: Job listings and applications
    servers:
      - url: https://api.example.com/v1
    paths:
      /jobs:
        get:
          operationId: listJobs
          # ...
    components:
      schemas:
        Job:
          # ...
    ```
    
    **Why good:** `operationId` becomes the client method name, `servers` enables environment switching, schemas in `components` are reusable via `$ref`
    
    See [examples/core.md](examples/core.md) for complete spec with paths, parameters, and responses.
    
    ---
    
    ### Pattern 2: Schema Design with 3.1 Syntax
    
    OpenAPI 3.1 uses JSON Schema Draft 2020-12. Key differences from 3.0: `nullable` is removed, use `type` arrays instead. `exclusiveMinimum`/`exclusiveMaximum` are numbers, not booleans.
    
    ```yaml
    # 3.1 nullable syntax
    type: ["string", "null"]
    
    # NOT 3.0 syntax:
    # type: string
    # nullable: true
    ```
    
    ```yaml
    components:
      schemas:
        Salary:
          type: object
          required: [min, max, currency]
          properties:
            min:
              type: integer
              minimum: 0
            max:
              type: integer
              minimum: 0
            currency:
              type: string
              minLength: 3
              maxLength: 3
              description: ISO 4217 currency code
    ```
    
    **Why good:** aligns with standard JSON Schema, tooling ecosystem understands it natively, `required` array is explicit
    
    See [examples/core.md](examples/core.md) for enum, format, and composition examples.
    
    ---
    
    ### Pattern 3: $ref Composition and Reuse
    
    Define schemas once in `components/schemas`, reference everywhere with `$ref`. Use `allOf` to extend base schemas, `oneOf` for polymorphism with discriminators.
    
    ```yaml
    components:
      schemas:
        PaginatedResponse:
          type: object
          required: [data, pagination]
          properties:
            pagination:
              $ref: "#/components/schemas/Pagination"
    
        JobListResponse:
          allOf:
            - $ref: "#/components/schemas/PaginatedResponse"
            - type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: "#/components/schemas/Job"
    ```
    
    **Why good:** single source of truth, changes propagate automatically, generated types reflect composition
    
    See [examples/core.md](examples/core.md) for `oneOf` with discriminator and `allOf` extension patterns.
    
    ---
    
    ### Pattern 4: Path Operations
    
    Operations define HTTP methods on paths. Always include `operationId`, `tags`, parameter schemas, and all response codes.
    
    ```yaml
    paths:
      /jobs/{jobId}:
        get:
          operationId: getJob
          tags: [Jobs]
          parameters:
            - name: jobId
              in: path
              required: true
              schema:
                type: string
                format: uuid
          responses:
            "200":
              description: Job details
              content:
                application/json:
                  schema:
                    $ref: "#/components/schemas/Job"
            "404":
              description: Job not found
              content:
                application/json:
                  schema:
                    $ref: "#/components/schemas/Error"
    ```
    
    **Why good:** `operationId` drives codegen method names, explicit `404` response documents error cases, `format: uuid` aids validation
    
    See [examples/core.md](examples/core.md) for query parameters, request bodies, and pagination.
    
    ---
    
    ### Pattern 5: TypeScript Type Generation
    
    Use `openapi-typescript` v7 to generate zero-runtime types from your spec. Types are generated as `.d.ts` files and imported with `import type`.
    
    ```bash
    npx openapi-typescript ./api/openapi.yaml -o ./api/schema.d.ts
    ```
    
    ```typescript
    import type { paths, components } from "./api/schema.d.ts";
    
    // Access schema types
    type Job = components["schemas"]["Job"];
    type Error = components["schemas"]["Error"];
    
    // Access response types
    type JobListResponse =
      paths["/jobs"]["get"]["responses"]["200"]["content"]["application/json"];
    ```
    
    **Why good:** zero runtime cost, types stay in sync with spec, no manual interface maintenance
    
    See [examples/codegen.md](examples/codegen.md) for CLI options, `redocly.yaml` multi-schema config, and programmatic API.
    
    ---
    
    ### Pattern 6: Type-Safe Fetch Client
    
    Use `openapi-fetch` (6kb) for a type-safe client that infers request/response types from generated types. No codegen needed beyond the types.
    
    ```typescript
    import createClient from "openapi-fetch";
    import type { paths } from "./api/schema.d.ts";
    
    const client = createClient<paths>({ baseUrl: "https://api.example.com/v1" });
    
    // Fully typed -- path params, query, body, response
    const { data, error } = await client.GET("/jobs/{jobId}", {
      params: { path: { jobId: "abc-123" } },
    });
    
    if (error) {
      // error is typed to the spec's error response schema
      console.error(error);
      return;
    }
    // data is typed to the spec's 200 response schema
    console.log(data.title);
    ```
    
    **Why good:** 6kb with virtually zero runtime, no manual generics, path/query/body/response all type-checked against the spec
    
    See [examples/codegen.md](examples/codegen.md) for middleware, auth headers, and error handling.
    
    </patterns>
    
    ---
    
    <decision_framework>
    
    ## Decision Framework
    
    ### Spec-First vs Code-First
    
    ```
    Is this a public or multi-consumer API?
    |-- YES --> Spec-first (design contract, get feedback, then implement)
    +-- NO  --> Is this a rapid prototype?
        |-- YES --> Code-first (generate spec from annotations)
        +-- NO  --> Does your framework generate OpenAPI from code?
            |-- YES --> Code-first (framework handles spec generation)
            +-- NO  --> Spec-first (write the YAML, generate types)
    ```
    
    ### Schema Composition
    
    ```
    Need to share fields across schemas?
    |-- YES --> allOf with a base $ref schema
    +-- NO  --> Need polymorphism (multiple possible shapes)?
        |-- YES --> oneOf with discriminator
        +-- NO  --> Need to combine constraints?
            |-- YES --> allOf (all must match)
            +-- NO  --> Simple schema with $ref for nested objects
    ```
    
    ### Type Generation Tooling
    
    | Need                       | Tool                    | When                                        |
    | -------------------------- | ----------------------- | ------------------------------------------- |
    | TypeScript types from spec | `openapi-typescript` v7 | Always -- zero-runtime type generation      |
    | Type-safe fetch client     | `openapi-fetch`         | Frontend or service-to-service calls        |
    | Full SDK generation        | `@hey-api/openapi-ts`   | Need Zod schemas, query hooks, or full SDKs |
    | Spec validation/linting    | Redocly CLI             | CI pipeline, pre-commit checks              |
    
    </decision_framework>
    
    ---
    
    <red_flags>
    
    ## RED FLAGS
    
    **High Priority:**
    
    - Using `nullable: true` -- removed in OpenAPI 3.1, use `type: ["string", "null"]`
    - Duplicating schemas inline instead of using `$ref` to `components/schemas` -- creates drift
    - Missing `operationId` on operations -- generated clients get ugly auto-generated names
    - Manually maintaining TypeScript interfaces that mirror the spec -- use `openapi-typescript` to generate them
    - Using `openapi: "3.0.x"` when 3.1 is available -- misses JSON Schema alignment
    
    **Medium Priority:**
    
    - Defining error responses without a shared `Error` schema -- inconsistent error shapes across endpoints
    - Missing `required` array on object schemas -- all properties become optional by default
    - Using `type: object` without `additionalProperties: false` when extra fields should be rejected
    - Not documenting `4xx`/`5xx` responses -- consumers don't know what error shapes to expect
    
    **Gotchas & Edge Cases:**
    
    - `$ref` siblings are ignored in 3.0 but allowed in 3.1 -- `description` next to `$ref` now works in 3.1
    - `exclusiveMinimum`/`exclusiveMaximum` changed from boolean (3.0) to number (3.1) -- `exclusiveMinimum: 0` means "greater than 0"
    - `discriminator` does not affect validation -- it's a hint for code generators, not a constraint
    - `discriminator.propertyName` must be a required string property at the same schema level
    - Inline schemas inside `discriminator` `oneOf` are not considered -- only `$ref` entries work
    - `openapi-typescript` generates `.d.ts` files -- these are type-only, no runtime code
    - `openapi-fetch` `data` is only present for 2xx responses, `error` for 4xx/5xx -- always check which is defined
    - Response bodies are consumed once -- clone the response if middleware needs to read it and pass it through
    - `openapi-typescript` v7 uses `redocly.yaml` for multi-schema config -- globbing is deprecated
    
    </red_flags>
    
    ---
    
    <critical_reminders>
    
    ## CRITICAL REMINDERS
    
    **(You MUST use OpenAPI 3.1 syntax -- `type: ["string", "null"]` NOT the 3.0 `nullable: true` keyword)**
    
    **(You MUST define reusable schemas in `components/schemas` and reference with `$ref` -- NO inline schema duplication)**
    
    **(You MUST include `operationId` on every path operation -- it becomes the generated client method name)**
    
    **(You MUST use `openapi-typescript` for type generation and import types with `import type` -- types are zero-runtime)**
    
    **Failure to follow these rules will cause schema drift, broken codegen, and type mismatches between spec and implementation.**
    
    </critical_reminders>
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.