ln-775-api-docs-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ln-775-api-docs-generator

Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-770-crosscutting-setup

Configures API documentation with Swagger/OpenAPI.

类型： L3 Worker 分类： 7XX项目初始化 父级： ln-770-crosscutting-setup

使用Swagger/OpenAPI配置API文档。

Overview

概述

Aspect	Details
Input	Context Store from ln-770
Output	Swagger/OpenAPI configuration
Stacks	.NET (Swashbuckle), Python (FastAPI built-in)

方面	详情
输入	来自ln-770的上下文存储
输出	Swagger/OpenAPI配置
技术栈	.NET（Swashbuckle）、Python（FastAPI内置）

Phase 1: Receive Context + Analyze API Structure

阶段1：接收上下文 + 分析API结构

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

接收上下文存储并扫描API端点。

必填上下文：

```
STACK
```
：.NET或Python
```
PROJECT_ROOT
```
：项目目录路径

幂等性检查：

.NET：搜索
```
AddSwaggerGen
```
或
```
UseSwagger
```
Python：FastAPI内置OpenAPI，检查自定义配置
如果已存在：返回
```
{ "status": "skipped" }
```

API分析：

扫描控制器/路由文件
识别认证方式（JWT、OAuth2、API密钥）
检查API版本控制

Phase 2: Research Documentation Standards

阶段2：研究文档标准

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

使用MCP工具获取当前文档规范。

适用于.NET：

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

适用于Python：

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

需研究的关键模式：

OpenAPI 3.0/3.1规范
安全方案定义
XML注释集成（.NET）
响应示例和模式
API版本控制文档

Phase 3: Decision Points

阶段3：决策点

Q1: API Information

问题1：API信息

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

字段	描述	必填
标题	API名称	✓ 是
版本	API版本（v1、v2）	✓ 是
描述	简要描述	可选
联系方式	支持联系方式	可选
许可证	API许可证	可选

Q2: Security Scheme

问题2：安全方案

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

方案	使用场景	OpenAPI类型
JWT Bearer（推荐）	在Authorization头中携带Token	`http` + `bearer`
API密钥	在Header或Query中携带密钥	`apiKey`
OAuth2	完整OAuth2流程	`oauth2`
无	公开API	无安全验证

Q3: Documentation Features

问题3：文档功能

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

功能	.NET	Python	默认设置
XML注释	✓ 支持	不适用	✓ 启用
响应示例	✓ 手动配置	✓ Pydantic	✓ 启用
请求验证	✓ 注解	✓ Pydantic	✓ 启用
在线调试	✓ 支持	✓ 支持	✓ 启用

Phase 4: Generate Configuration

阶段4：生成配置

.NET Output Files

.NET输出文件

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:

csharp

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

csproj Update:

xml

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

文件	用途
`Extensions/SwaggerExtensions.cs`	Swagger服务注册
`*.csproj` （更新）	启用XML文档

生成流程：

使用MCP参考获取当前Swashbuckle API规范
生成SwaggerExtensions，包含：
- AddEndpointsApiExplorer
- 带OpenApiInfo的AddSwaggerGen
- （如果检测到认证）安全定义
- XML注释包含
更新csproj以启用文档生成

需添加的包：

```
Swashbuckle.AspNetCore
```

注册代码：

csharp

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

csproj更新：

xml

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

Python Output Files

Python输出文件

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:

python

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

文件	用途
`core/openapi_config.py`	OpenAPI自定义配置

生成流程：

使用MCP参考获取FastAPI OpenAPI自定义规范
生成openapi_config.py，包含：
- 自定义OpenAPI模式
- 安全方案定义
- 标签和描述
FastAPI自动生成OpenAPI

注意： FastAPI内置OpenAPI支持。此Worker用于自定义默认配置。

注册代码：

python

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

Phase 5: Validate

阶段5：验证

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

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

OpenAPI spec validation:

bash

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

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

验证步骤：

语法检查：

.NET：
```
dotnet build --no-restore
```

Python：

python -m py_compile core/openapi_config.py

访问文档：

技术栈地址
.NET http://localhost:5000/swagger
Python http://localhost:5000/docs
Python（ReDoc） http://localhost:5000/redoc
验证内容：
- 所有端点可见
- 请求/响应模式已显示
- 安全方案已展示（若已配置）
- 在线调试功能可用

技术栈	地址
.NET	http://localhost:5000/swagger
Python	http://localhost:5000/docs
Python（ReDoc）	http://localhost:5000/redoc

OpenAPI规范验证：

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)

JWT Bearer（.NET）

csharp

// 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"
});

csharp

// 仅结构展示 - 实际代码通过MCP参考生成
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)

JWT Bearer（Python/FastAPI）

python

undefined

python

// 仅结构展示 - 实际代码通过MCP参考生成
from fastapi.security import HTTPBearer
security = HTTPBearer()

Structure only - actual code generated via MCP ref

返回至协调器

from fastapi.security import HTTPBearer security = HTTPBearer()

---

json

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

Return to Coordinator

参考链接

json

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

版本： 2.0.0 最后更新： 2026-01-10

Reference Links

—

Version: 2.0.0 Last Updated: 2026-01-10

—