OpenAPI Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: openapi for comprehensive documentation.

Basic Structure

openapi: 3.1.0
info:
  title: User API
  version: 1.0.0
  description: API for managing users

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User found
        '404':
          description: User not found

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
      required: [id, name, email]

    CreateUser:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
      required: [name, email]

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

Schema Types

# String with validation
type: string
minLength: 1
maxLength: 100
pattern: '^[a-zA-Z]+$'
format: email | date | date-time | uri | uuid

# Number
type: integer
minimum: 0
maximum: 100

# Enum
type: string
enum: [active, inactive, pending]

# Array
type: array
items:
  type: string
minItems: 1
maxItems: 10

# Object
type: object
additionalProperties: false

When NOT to Use This Skill

• GraphQL API documentation (use graphql skill)
• tRPC type-safe APIs (use trpc skill)
• Generating API clients (use openapi-codegen skill)
• Spring Boot API documentation (use springdoc-openapi skill)
• Code-first API development (consider using annotations/decorators)

Anti-Patterns

Anti-Pattern	Why It's Bad	Solution
Missing response schemas	No type safety, poor docs	Define schemas for all responses
No examples in schemas	Hard to understand API	Add example or examples to all schemas
Using only object without properties	Loses type information	Define explicit properties with types
Not defining error responses	Incomplete API contract	Document 4xx and 5xx responses
Hardcoding server URLs	Environment-specific config in spec	Use server variables or multiple servers
Missing required fields	Ambiguous API contract	Mark all required fields explicitly
Duplicate schema definitions	Maintenance nightmare	Use $ref and components
No security schemes defined	Unclear authentication	Define security schemes in components
Missing operationId	Poor code generation	Add unique operationId to each endpoint
Using additionalProperties: true everywhere	Loses validation benefits	Set to false unless needed

Quick Troubleshooting

Issue	Possible Cause	Solution
Validation errors in spec	Invalid YAML/JSON syntax	Use @redocly/cli lint or Swagger Editor
Code generation fails	Missing operationId or invalid refs	Add operationIds, verify all $refs resolve
Swagger UI not loading	CORS or invalid spec	Check browser console, validate spec
Type errors in generated code	Schema mismatch with implementation	Ensure schemas match actual API responses
Missing fields in generated types	Schema not defining all properties	Add all properties to schema definition
Circular reference errors	Self-referencing schemas	Use allOf or refactor schema structure
Example validation fails	Example doesn't match schema	Ensure examples conform to schema constraints
Missing auth in Swagger UI	Security not configured	Add securitySchemes and security requirements

Production Readiness

Complete Error Responses

components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          example: 'NOT_FOUND'
        message:
          type: string
          example: 'User not found'
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
      required: [code, message]

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 'VALIDATION_ERROR'
            message: 'Invalid input'
            details:
              - field: 'email'
                message: 'Invalid email format'

    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    RateLimited:
      description: Too many requests
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

paths:
  /users:
    post:
      responses:
        '201':
          description: Created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

Pagination

components:
  schemas:
    PaginatedResponse:
      type: object
      properties:
        data:
          type: array
          items: {}
        pagination:
          type: object
          properties:
            page:
              type: integer
            limit:
              type: integer
            total:
              type: integer
            totalPages:
              type: integer

  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    LimitParam:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

paths:
  /users:
    get:
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      data:
                        items:
                          $ref: '#/components/schemas/User'

Code Generation

# Generate TypeScript types
npx openapi-typescript ./openapi.yaml -o ./src/types/api.ts

# Generate client SDK
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./src/api-client

# Validate spec
npx @redocly/cli lint openapi.yaml

// Generated type usage
import type { paths, components } from './types/api';

type User = components['schemas']['User'];
type CreateUserRequest = paths['/users']['post']['requestBody']['content']['application/json'];
type UserListResponse = paths['/users']['get']['responses']['200']['content']['application/json'];

Testing

// Contract testing with OpenAPI
import SwaggerParser from '@apidevtools/swagger-parser';
import { expect, test } from 'vitest';

test('OpenAPI spec is valid', async () => {
  const api = await SwaggerParser.validate('./openapi.yaml');
  expect(api.info.title).toBeDefined();
});

// API response validation
import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv({ strict: false });
addFormats(ajv);

test('GET /users returns valid response', async () => {
  const response = await fetch('/api/users');
  const data = await response.json();

  const validate = ajv.compile(userListSchema);
  expect(validate(data)).toBe(true);
});

Monitoring Metrics

Metric	Target
Spec validation errors	0
Breaking changes	0 (semver)
Documentation coverage	100%
Example coverage	> 80%

Checklist

• Standard error response schema
• Pagination parameters defined
• All responses documented
• Security schemes defined
• Request/response examples
• Reusable components
• Code generation configured
• Spec validation in CI
• Contract tests
• Versioning strategy

Frontend Integration

OpenAPI specs can be consumed by frontend applications to generate type-safe clients.

Workflow

OpenAPI Spec → Code Generation → Type-Safe Client → Frontend App

Related Skills

Skill	Purpose
HTTP Clients	Axios, Fetch, ky, ofetch patterns
OpenAPI Codegen	Generate clients from specs
Type-Safe API	End-to-end type safety

Quick Client Generation

# Generate TypeScript types only
npx openapi-typescript ./openapi.yaml -o ./src/types/api.ts

# Generate full client
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./src/api-client

# swagger-typescript-api (simpler)
npx swagger-typescript-api -p ./openapi.yaml -o ./src/api --axios

Type Usage in Frontend

import type { paths, components } from './types/api';
import { createApiClient } from './api-client';

// Type-safe request/response
type User = components['schemas']['User'];
type CreateUserBody = paths['/users']['post']['requestBody']['content']['application/json'];
type UsersResponse = paths['/users']['get']['responses']['200']['content']['application/json'];

// With generated client
const api = createApiClient({ baseUrl: '/api' });
const users = await api.users.list(); // Fully typed

Reference Documentation

• Parameters
• Security
• Frontend Integration