Generate Api Docs by jeremylongshore

Automatically generate comprehensive OpenAPI 3.0 specifications with interactive documentation, automated testing, and multi-language client SDKs from your existing API codebase or by analyzing live endpoints.

When to Use This Command

Use /generate-api-docs when you need to:

• Document existing APIs without manual specification writing
• Generate interactive API documentation for developers
• Create Postman/Insomnia collections from your API
• Enable "try it out" functionality for API endpoints
• Generate client SDKs in multiple languages
• Maintain API documentation synchronized with code
• Create API reference documentation for external consumers
• Validate API contracts and schemas
• Enable API mocking for frontend development

DON'T use this when:

• Your API is still in early design phase (use /api-contract-generator instead)
• You only need internal code comments (use JSDoc/docstrings)
• Building GraphQL APIs (use /build-graphql-server with introspection)
• APIs have no stable contract (too early in development)

Design Decisions

This command implements OpenAPI 3.0.3 specification as the primary approach because:

• Industry standard adopted by major organizations
• Extensive tooling ecosystem (Swagger UI, Redoc, SDKs)
• Supports complex schemas including oneOf, allOf, discriminators
• Native support for webhooks and callbacks
• JSON Schema validation built-in
• Multiple security schemes support

Alternative considered: API Blueprint

• Markdown-based format
• Simpler for human writing
• Less tooling support
• Recommended for documentation-first design

Alternative considered: RAML

• YAML-based with reusable components
• Good for large enterprise APIs
• Smaller ecosystem
• Recommended when modularity is critical

Alternative considered: AsyncAPI

• Specialized for event-driven APIs
• WebSocket and message queue support
• Use alongside OpenAPI for complete coverage

Prerequisites

Before running this command:

1. Functioning API with consistent patterns
2. Request/response examples available
3. Authentication mechanism implemented
4. Error response format standardized
5. API versioning strategy defined

Implementation Process

Step 1: API Analysis and Discovery

Scan codebase and running API to discover all endpoints, methods, and data structures.

Step 2: Schema Extraction

Extract request/response schemas from code annotations, TypeScript types, or runtime analysis.

Step 3: OpenAPI Generation

Generate complete OpenAPI 3.0 specification with all paths, schemas, and security definitions.

Step 4: Documentation Enhancement

Add descriptions, examples, and grouping tags for better organization and understanding.

Step 5: Interactive Documentation Setup

Deploy Swagger UI and Redoc for interactive API exploration and testing.

Output Format

The command generates:

• openapi.yaml - Main OpenAPI 3.0 specification
• openapi.json - JSON format for tooling
• docs/ - Static HTML documentation
• index.html - Swagger UI interface
• redoc.html - Redoc documentation
• collections/ - External tool formats
• postman_collection.json - Postman import
• insomnia_workspace.json - Insomnia import
• bruno_collection.bru - Bruno collection
• examples/ - Request/response examples
• schemas/ - Extracted JSON schemas
• README.md - Getting started guide

Code Examples

Example 1: Express.js API with Automatic Documentation Generation

// api-documentation-generator.js
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');
const { z } = require('zod');
const zodToJsonSchema = require('zod-to-json-schema');
const express = require('express');
const fs = require('fs').promises;
const path = require('path');
const yaml = require('js-yaml');

class APIDocumentationGenerator {
  constructor(app, config = {}) {
    this.app = app;
    this.config = {
      title: config.title || 'API Documentation',
      version: config.version || '1.0.0',
      description: config.description || 'API Documentation',
      servers: config.servers || [{ url: 'http://localhost:3000' }],
…

Example 2: Python FastAPI with Automatic OpenAPI Enhancement

# api_doc_enhancer.py
from fastapi import FastAPI, APIRouter, Depends, HTTPException
from fastapi.openapi.utils import get_openapi
from fastapi.openapi.docs import get_swagger_ui_html, get_redoc_html
from pydantic import BaseModel, Field
from typing import List, Optional, Dict, Any
import json
import yaml
from pathlib import Path
import httpx
from datetime import datetime

class OpenAPIEnhancer:
    """Enhance FastAPI's auto-generated OpenAPI with additional features"""

    def __init__(self, app: FastAPI):
        self.app = app
        self.examples = {}
…