Overview

Docs Kit integrates with OpenAPI (Swagger) specifications to automatically generate interactive API documentation. Simply provide your OpenAPI spec and reference endpoints in your MDX files.

What You Get

When configured, OpenAPI integration provides:

• Automatic parameter documentation
• Request body schemas with examples
• Response schemas for all status codes
• Interactive "Try It" button
• Code generation in 7+ languages
• Authentication handling
• Schema visualization

Quick Setup

# Download or copy your OpenAPI spec
cp openapi.json public/openapi.json

{
  "openapi": {
    "specPath": "public/openapi.json"
  }
}

---
title: "Get User"
description: "Retrieve user by ID"
openapi: "GET /api/users/{id}"
published: true
---

Additional context about this endpoint...

bun dev

OpenAPI Spec Location

Local File

Store the spec in your project:

{
  "openapi": {
    "specPath": "public/openapi.json"
  }
}

Directory structure:

public/
  static/
    openapi.json

Remote URL

Reference a hosted specification:

{
  "openapi": {
    "specPath": "https://api.example.com/openapi.json"
  }
}

Benefits:

• Always up-to-date with API changes
• No need to commit large spec files
• Shared across multiple documentation sites

OpenAPI Specification Format

Docs Kit supports OpenAPI 3.0+ specifications:

{
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.example.com"
    }
  ],
  "paths": {
    "/users/{id}": {
      "get": {
        "summary": "Get user by ID",
        "parameters": [...],
        "responses": {...}
      }
    }
  },
  "components": {
    "schemas": {...},
    "securitySchemes": {...}
  }
}

Configuration Options

"specPath": "public/openapi.json"

"specPath": "https://api.example.com/spec.json"

Validating Your Spec

Before using your spec, validate it:

Online Validators

• Swagger Editor - Paste and validate
• OpenAPI.tools - Validation tools

CLI Validation

# Using Swagger CLI
npm install -g @apidevtools/swagger-cli
swagger-cli validate public/openapi.json

# Using Redocly CLI
npm install -g @redocly/cli
redocly lint public/openapi.json

Common Issues

Spec Not Loading

If the spec doesn't load, check:

1. File path - Verify specPath matches actual location
2. Valid JSON - Ensure proper JSON syntax
3. OpenAPI version - Use OpenAPI 3.0+
4. Server restart - Restart dev server after config changes

CORS Issues with Remote Specs

If using a remote URL, ensure the API server sends proper CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET

Large Spec Files

For large specs (>5MB), consider:

1. Splitting into multiple smaller specs
2. Hosting remotely and using URL
3. Removing unused schemas/paths

Multiple API Versions

Document different API versions using separate specs:

{
  "openapi": {
    "specPath": "public/openapi-v2.json"
  }
}

Create version-specific pages:

content/
  api-reference-v1/
    endpoints/...
  api-reference-v2/
    endpoints/...

Best Practices

Keep Spec Updated

• Automated: Generate spec from code (code-first approach)
• Version control: Commit spec to repository
• CI/CD: Validate spec in pipeline

Use Descriptions

Add rich descriptions to all endpoints:

{
  "paths": {
    "/users": {
      "get": {
        "summary": "List users",
        "description": "Retrieve a paginated list of users with optional filtering. Supports sorting by creation date, email, or username.",
        "..."
      }
    }
  }
}

Include Examples

Provide examples in your spec:

{
  "components": {
    "schemas": {
      "User": {
        "properties": {
          "email": {
            "type": "string",
            "example": "user@example.com"
          }
        }
      }
    }
  }
}

Define Security Schemes

Document authentication requirements:

{
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}

Next Steps

Continue to Creating API Pages to start documenting your endpoints.