ln-775-api-docs-generator
Type: L3 Worker
Category: 7XX Project Bootstrap
Configures API documentation with Swagger/OpenAPI.
Overview
| Aspect |
Details |
| Input |
Context Store from ln-770 |
| Output |
Swagger/OpenAPI configuration |
| Stacks |
.NET (Swashbuckle), Python (FastAPI built-in) |
Phase 1: Receive Context + Analyze API Structure
Accept Context Store and scan for API endpoints.
Required Context:
STACK: .NET or PythonPROJECT_ROOT: Project directory path
Idempotency Check:
- .NET: Grep for
AddSwaggerGen or UseSwagger
- Python: FastAPI has built-in OpenAPI, check for custom configuration
- If found: Return
{ "status": "skipped" }
API Analysis:
- Scan for controller/router files
- Identify authentication method (JWT, OAuth2, API Key)
- Check for API versioning
Phase 2: Research Documentation Standards
Use MCP tools for current documentation.
For .NET:
MCP ref: "Swashbuckle ASP.NET Core OpenAPI Swagger configuration"
Context7: /domaindrivendev/Swashbuckle.AspNetCore
For Python:
MCP ref: "FastAPI OpenAPI documentation customization"
Context7: /tiangolo/fastapi
Key Patterns to Research:
- OpenAPI 3.0/3.1 specification
- Security scheme definitions
- XML comments integration (.NET)
- Response examples and schemas
- API versioning documentation
Phase 3: Decision Points
Q1: API Information
| Field |
Description |
Required |
| Title |
API name |
✓ Yes |
| Version |
API version (v1, v2) |
✓ Yes |
| Description |
Brief description |
Optional |
| Contact |
Support contact |
Optional |
| License |
API license |
Optional |
Q2: Security Scheme
| Scheme |
Use Case |
OpenAPI Type |
| JWT Bearer (Recommended) |
Token in Authorization header |
http + bearer |
| API Key |
Key in header or query |
apiKey |
| OAuth2 |
Full OAuth2 flow |
oauth2 |
| None |
Public API |
No security |
Q3: Documentation Features
| Feature |
.NET |
Python |
Default |
| XML Comments |
✓ Supported |
N/A |
✓ Enable |
| Response Examples |
✓ Manual |
✓ Pydantic |
✓ Enable |
| Request Validation |
✓ Annotations |
✓ Pydantic |
✓ Enable |
| Try It Out |
✓ Yes |
✓ Yes |
✓ Enable |
Phase 4: Generate Configuration
.NET Output Files
| File |
Purpose |
Extensions/SwaggerExtensions.cs |
Swagger service registration |
*.csproj (update) |
Enable XML documentation |
Generation Process:
- Use MCP ref for current Swashbuckle API
- Generate SwaggerExtensions with:
- AddEndpointsApiExplorer
- AddSwaggerGen with OpenApiInfo
- Security definition (if auth detected)
- XML comments inclusion
- Update csproj for documentation generation
Packages to Add:
Registration Code:
builder.Services.AddSwaggerServices();
app.UseSwaggerServices();
csproj Update:
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
Python Output Files
| File |
Purpose |
core/openapi_config.py |
OpenAPI customization |
Generation Process:
- Use MCP ref for FastAPI OpenAPI customization
- Generate openapi_config.py with:
- Custom OpenAPI schema
- Security scheme definitions
- Tags and descriptions
- FastAPI generates OpenAPI automatically
Note: FastAPI has built-in OpenAPI support. This worker customizes the default configuration.
Registration Code:
from core.openapi_config import custom_openapi
app.openapi = lambda: custom_openapi(app)
Phase 5: Validate
Validation Steps:
-
Syntax check:
- .NET:
dotnet build --no-restore
- Python:
python -m py_compile core/openapi_config.py
-
Access documentation:
-
Verify content:
-
OpenAPI spec validation:
curl http://localhost:5000/swagger/v1/swagger.json | jq .
curl http://localhost:5000/openapi.json | jq .
Security Scheme Examples
JWT Bearer (.NET)
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)
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
Critical Rules
- Use MCP ref for current Swashbuckle/FastAPI API — do not hardcode configuration from memory
- Auto-detect auth scheme — scan for JWT, OAuth2, or API Key and configure security definition accordingly
- Enable XML documentation in .NET — update csproj with
GenerateDocumentationFile and suppress warning 1591
- FastAPI: customize, not replace — built-in OpenAPI works by default, only add custom schema/security
- Idempotent — if
AddSwaggerGen/UseSwagger exists, return status: "skipped"
Definition of Done
Version: 2.0.0
Last Updated: 2026-01-10
