ln-775-api-docs-generator

Overview

Phase 1: Receive Context + Analyze API Structure

• STACK

  : .NET or Python

• PROJECT_ROOT

  : Project directory path

• .NET: Grep for

  AddSwaggerGen

  or

  UseSwagger

• Python: FastAPI has built-in OpenAPI, check for custom configuration
• If found: Return

  { "status": "skipped" }

1. Scan for controller/router files
2. Identify authentication method (JWT, OAuth2, API Key)
3. Check for API versioning

Phase 2: Research Documentation Standards

MCP ref: "Swashbuckle ASP.NET Core OpenAPI Swagger configuration"
Context7: /domaindrivendev/Swashbuckle.AspNetCore

MCP ref: "FastAPI OpenAPI documentation customization"
Context7: /tiangolo/fastapi

1. OpenAPI 3.0/3.1 specification
2. Security scheme definitions
3. XML comments integration (.NET)
4. Response examples and schemas
5. API versioning documentation

Phase 3: Decision Points

Q1: API Information

Q2: Security Scheme

http

bearer

apiKey

oauth2

Q3: Documentation Features

Phase 4: Generate Configuration

.NET Output Files

Extensions/SwaggerExtensions.cs

*.csproj

1. Use MCP ref for current Swashbuckle API
2. Generate SwaggerExtensions with:
   • AddEndpointsApiExplorer
   • AddSwaggerGen with OpenApiInfo
   • Security definition (if auth detected)
   • XML comments inclusion
3. Update csproj for documentation generation

• Swashbuckle.AspNetCore

builder.Services.AddSwaggerServices();
// ...
app.UseSwaggerServices();

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Python Output Files

core/openapi_config.py

1. Use MCP ref for FastAPI OpenAPI customization
2. Generate openapi_config.py with:
   • Custom OpenAPI schema
   • Security scheme definitions
   • Tags and descriptions
3. FastAPI generates OpenAPI automatically

from core.openapi_config import custom_openapi
app.openapi = lambda: custom_openapi(app)

Phase 5: Validate

1. Syntax check:
   • .NET:

     dotnet build --no-restore

   • Python:

     python -m py_compile core/openapi_config.py

2. Access documentation:

   Stack	URL
   .NET	http://localhost:5000/swagger
   Python	http://localhost:5000/docs
   Python (ReDoc)	http://localhost:5000/redoc

3. Verify content:
   • All endpoints visible
   • Request/response schemas displayed
   • Security scheme shown (if configured)
   • Try It Out functional
4. OpenAPI spec validation:
   bash

   # .NET
   curl http://localhost:5000/swagger/v1/swagger.json | jq .
   
   # Python
   curl http://localhost:5000/openapi.json | jq .

Security Scheme Examples

JWT Bearer (.NET)

// Structure only - actual code generated via MCP ref
options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
    Description = "JWT Authorization header using Bearer scheme",
    Name = "Authorization",
    In = ParameterLocation.Header,
    Type = SecuritySchemeType.Http,
    Scheme = "bearer",
    BearerFormat = "JWT"
});

JWT Bearer (Python/FastAPI)

# Structure only - actual code generated via MCP ref
from fastapi.security import HTTPBearer
security = HTTPBearer()

Return to Coordinator

{
  "status": "success",
  "files_created": [
    "Extensions/SwaggerExtensions.cs"
  ],
  "packages_added": [
    "Swashbuckle.AspNetCore"
  ],
  "registration_code": "builder.Services.AddSwaggerServices();",
  "message": "Configured Swagger/OpenAPI documentation"
}

Reference Links

• Swashbuckle.AspNetCore
• FastAPI OpenAPI
• OpenAPI Specification