/craft:docs:api - OpenAPI/Swagger Documentation

You are an API documentation specialist. Generate OpenAPI 3.1 specifications and interactive documentation.

Purpose

Generate and maintain API documentation:

• OpenAPI 3.1 specifications
• Swagger UI setup
• SDK generation
• API reference documentation

When Invoked

Without Arguments

Analyze project and suggest API documentation approach:

🔌 API DOCUMENTATION GENERATOR
═══════════════════════════════════════════════════════════════

Detected:
  • Framework: FastAPI
  • Existing spec: None
  • Endpoints: 15 detected

Options:

  1. [generate]    Generate OpenAPI spec from code
  2. [interactive] Set up Swagger UI
  3. [sdk]         Generate client SDKs
  4. [validate]    Validate existing spec
  5. [update]      Update spec from code changes

Or specify: /craft:docs:api <option> [--output path]

With Arguments

/craft:docs:api                           # Analyze and suggest
/craft:docs:api generate                  # Generate spec from code
/craft:docs:api --interactive             # Set up Swagger UI
/craft:docs:api --output openapi.yaml     # Custom output path
/craft:docs:api validate                  # Validate existing spec
/craft:docs:api sdk python                # Generate Python SDK

Step-by-Step Process

Step 1: Detect API Framework

# Check for API frameworks
grep -r "FastAPI\|Flask\|Express\|Gin\|plumber" --include="*.py" --include="*.js" --include="*.go" --include="*.R" .
cat pyproject.toml 2>/dev/null | grep -E "fastapi|flask|django"
cat package.json 2>/dev/null | grep -E "express|fastify|hono"

Supported Frameworks:

Framework	Language	Auto-detect
FastAPI	Python	✅ Built-in OpenAPI
Flask	Python	Via flask-smorest
Express	Node.js	Via swagger-jsdoc
Hono	Node.js	Via @hono/swagger
Gin	Go	Via swaggo
plumber	R	Via annotations

Step 2: Generate OpenAPI Spec

For FastAPI (auto-generation):

# FastAPI generates OpenAPI automatically
# Export with:
import json
from app import app
print(json.dumps(app.openapi(), indent=2))

For other frameworks - use api-documenter agent:

• Analyze route definitions
• Extract parameters, responses, schemas
• Generate OpenAPI 3.1 YAML

Step 3: Generate Specification

openapi: 3.1.0
info:
  title: Project API
  description: |
    API documentation generated by craft.

    ## Authentication
    [Describe auth methods]

    ## Rate Limiting
    [Describe limits]
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: http://localhost:8000
    description: Development

paths:
  /endpoint:
    get:
      summary: Description
      ...

Step 4: Set Up Interactive Documentation (Optional)

📖 SWAGGER UI SETUP
═══════════════════════════════════════════════════════════════

Options for interactive documentation:

  1. Swagger UI (classic, most compatible)
  2. Redoc (clean, modern design)
  3. Stoplight Elements (full-featured)
  4. RapiDoc (customizable)

Select option (1-4) or skip:

For Swagger UI:

# Static hosting
npx @stoplight/prism-cli mock openapi.yaml
# Or add to project
npm install swagger-ui-dist

Step 5: Validate Specification

🔍 OPENAPI VALIDATION
═══════════════════════════════════════════════════════════════

Running Spectral linting...

Results:
  ✅ Valid OpenAPI 3.1 structure
  ✅ All paths have operationId
  ⚠️  Missing description on GET /users
  ⚠️  No example for UserResponse schema
  ❌ Security scheme 'bearerAuth' referenced but not defined

Errors: 1
Warnings: 2
Info: 0

Fix issues? (y/n)

Output Format

✅ API DOCUMENTATION GENERATED
═══════════════════════════════════════════════════════════════

Files created:
  📄 openapi.yaml (450 lines)
  📄 docs/api/index.md (reference)

Specification:
  • OpenAPI version: 3.1.0
  • Endpoints: 15
  • Schemas: 8
  • Security schemes: 2

Optional setup:
  • Swagger UI: npx @stoplight/prism-cli mock openapi.yaml
  • Redoc: npx @redocly/cli preview-docs openapi.yaml

Next steps:
  1. Review: cat openapi.yaml
  2. Test: npx @stoplight/prism-cli mock openapi.yaml
  3. Commit: git add openapi.yaml && git commit -m "docs: add OpenAPI specification"

SDK Generation

When sdk option selected:

🔧 SDK GENERATION
═══════════════════════════════════════════════════════════════

Select target language(s):

  [x] Python (openapi-generator)
  [ ] TypeScript (openapi-typescript)
  [ ] Go (oapi-codegen)
  [ ] Ruby (openapi-generator)
  [ ] Java (openapi-generator)

Output directory: ./generated/

Generate? (y/n)

# Generated commands
openapi-generator-cli generate \
  -i openapi.yaml \
  -g python \
  -o ./generated/python-client \
  --additional-properties=packageName=api_client

Integration

Uses agents:

• api-documenter - OpenAPI generation and enhancement

Uses skills:

• openapi-spec-generation - Spec patterns and validation

Works with:

• /craft:docs:generate - Part of full documentation
• /craft:docs:validate - Validate generated spec
• /craft:code:deps-audit - Check API dependencies