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