ln-775-api-docs-generator

SKILL.md

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 Python

PROJECT_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:

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

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

Swashbuckle.AspNetCore

FastAPI OpenAPI

OpenAPI Specification

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

 Context Store received (stack, project root)

 API structure analyzed (controllers/routers, auth method, versioning)

 Documentation standards researched via MCP tools

 Swagger/OpenAPI configuration generated with API info and security scheme

 XML comments enabled (.NET) or custom OpenAPI schema configured (Python)

 Syntax validated (dotnet build or py_compile)

 Structured JSON response returned to ln-770 coordinator

Version: 2.0.0
Last Updated: 2026-01-10