ln-775-api-docs-generator

ln-775-api-docs-generator

类型： L3 Worker 类别： 7XX 项目引导

使用 Swagger/OpenAPI 配置 API 文档。

---

概述

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

---

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

接收 Context Store 并扫描 API 端点。

所需上下文：

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

幂等性检查：

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

API 分析：

1. 扫描控制器/路由器文件
2. 确定身份验证方式（JWT、OAuth2、API Key）
3. 检查是否使用 API 版本控制

---

阶段 2：研究文档标准

使用 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

需要研究的关键模式：

1. OpenAPI 3.0/3.1 规范
2. 安全方案定义
3. XML 注释集成（.NET）
4. 响应示例和架构
5. API 版本控制文档

---

阶段 3：决策点

Q1：API 信息

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

Q2：安全方案

方案	使用场景	OpenAPI 类型
JWT Bearer（推荐）	Authorization 标头中的令牌	http + bearer
API Key	标头或查询参数中的密钥	apiKey
OAuth2	完整的 OAuth2 流程	oauth2
无	公共 API	无安全设置

Q3：文档功能

功能	.NET	Python	默认值
XML 注释	✓ 支持	不适用	✓ 启用
响应示例	✓ 手动	✓ Pydantic	✓ 启用
请求验证	✓ 注释	✓ Pydantic	✓ 启用
Try It Out	✓ 是	✓ 是	✓ 启用

---

阶段 4：生成配置

.NET 输出文件

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

生成流程：

1. 使用 MCP ref 获取最新 Swashbuckle API
2. 生成 SwaggerExtensions，包含：
   • AddEndpointsApiExplorer
   • AddSwaggerGen 和 OpenApiInfo
   • 安全定义（如果检测到身份验证）
   • 包含 XML 注释
3. 更新 csproj 以生成文档

要添加的程序包：

• Swashbuckle.AspNetCore

注册代码：

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

csproj 更新：

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

Python 输出文件

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

生成流程：

1. 使用 MCP ref 获取 FastAPI OpenAPI 自定义配置的最新信息
2. 生成 openapi_config.py，包含：
   • 自定义 OpenAPI 架构
   • 安全方案定义
   • 标签和描述
3. FastAPI 会自动生成 OpenAPI

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

注册代码：

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

---

阶段 5：验证

验证步骤：

1. 语法检查：

   • .NET：dotnet build --no-restore
   • Python：python -m py_compile core/openapi_config.py

2. 访问文档：

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

3. 验证内容：

   • 所有端点均可见
   • 已显示请求/响应架构
   • 已显示安全方案（如已配置）
   • Try It Out 功能正常

4. OpenAPI 规范验证：

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

---

安全方案示例

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()

---

返回协调器

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

---

参考链接

• Swashbuckle.AspNetCore
• FastAPI OpenAPI
• OpenAPI 规范

---

关键规则

• 使用 MCP ref 获取当前的 Swashbuckle/FastAPI API 信息 — 不要凭记忆硬编码配置
• 自动检测身份验证方案 — 扫描 JWT、OAuth2 或 API Key，并据此配置安全定义
• 在 .NET 中启用 XML 文档 — 使用 GenerateDocumentationFile 更新 csproj，并抑制警告 1591
• FastAPI：自定义，而非替换 — 内置 OpenAPI 默认可用，只需添加自定义架构/安全配置
• 幂等 — 如果已存在 AddSwaggerGen/UseSwagger，则返回 status: "skipped"

完成标准

• 已接收 Context Store（技术栈、项目根目录）
• 已分析 API 结构（控制器/路由器、身份验证方法、版本管理）
• 已通过 MCP 工具研究文档规范
• 已生成包含 API 信息和安全方案的 Swagger/OpenAPI 配置
• 已启用 XML 注释（.NET）或配置自定义 OpenAPI 架构（Python）
• 已验证语法（dotnet build 或 py_compile）
• 已向 ln-770 协调器返回结构化 JSON 响应

---

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