ln-775-api-docs-generator
Configures Swagger/OpenAPI documentation
When & Why to Use This Skill
This Claude skill automates the configuration of Swagger and OpenAPI documentation for .NET (Swashbuckle) and Python (FastAPI) projects. It streamlines the creation of interactive API documentation, ensures compliance with OpenAPI 3.0/3.1 standards, and integrates complex security schemes like JWT and OAuth2, significantly reducing manual setup time and improving API discoverability.
Use Cases
- Automatically setting up Swagger UI in a new .NET Web API project to provide frontend teams with an interactive playground for endpoint testing.
- Customizing FastAPI's built-in OpenAPI schema to include detailed metadata, tags, and security requirements for production-ready microservices.
- Enabling XML comment integration in .NET projects to automatically generate descriptive API documentation from source code comments.
- Standardizing API security definitions and versioning across multiple services to ensure a consistent and professional developer experience.
| name | ln-775-api-docs-generator |
|---|---|
| description | Configures Swagger/OpenAPI documentation |
ln-775-api-docs-generator
Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-770-crosscutting-setup
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
AddSwaggerGenorUseSwagger - 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:
Swashbuckle.AspNetCore
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
- .NET:
Access documentation:
Stack URL .NET http://localhost:5000/swagger Python http://localhost:5000/docs Python (ReDoc) http://localhost:5000/redoc Verify content:
- All endpoints visible
- Request/response schemas displayed
- Security scheme shown (if configured)
- Try It Out functional
OpenAPI spec validation:
# .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
Version: 2.0.0 Last Updated: 2026-01-10