Openapi

---
name: openapi
description: |
  OpenAPI/Swagger specification. Covers schema definition, paths,
  and documentation. Use for API documentation.

  USE WHEN: user mentions "OpenAPI", "Swagger", "API spec", "API documentation",
  "schema definition", "OpenAPI 3.0", "Swagger UI", asks about "how to write OpenAPI spec",
  "document REST API", "API contract", "schema validation"

  DO NOT USE FOR: GraphQL schemas - use `graphql` instead; tRPC - use `trpc` instead;
  Generating clients from OpenAPI - use `openapi-codegen` instead;
  Spring Boot OpenAPI - use `springdoc-openapi` instead
allowed-tools: Read, Grep, Glob, Write, Edit
---
# OpenAPI Core Knowledge

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

## Basic Structure

```yaml
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

```yaml
# 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

```yaml
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

```yaml
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

```bash
# 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
```

```typescript
// 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

```typescript
// 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](../../api-integration/http-clients/SKILL.md) | Axios, Fetch, ky, ofetch patterns |
| [OpenAPI Codegen](../../api-integration/openapi-codegen/SKILL.md) | Generate clients from specs |
| [Type-Safe API](../../api-integration/type-safe-api/SKILL.md) | End-to-end type safety |

### Quick Client Generation

```bash
# 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

```typescript
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](quick-ref/parameters.md)
- [Security](quick-ref/security.md)
- [Frontend Integration](quick-ref/frontend-integration.md)