用途
ln-775-api-docs-generator 是一个 L3 Worker 技能，属于 7XX Project Bootstrap 分类，用于为后端 API 配置 Swagger/OpenAPI 文档。当需要为项目添加交互式 API 文档时使用。
主要能力
该技能接收来自 ln-770 的 Context Store 作为输入，输出 Swagger/OpenAPI 配置。支持的技术栈包括 .NET（Swashbuckle）和 Python（FastAPI 内置）。
工作流程分为五个阶段：
-
接收上下文并分析 API 结构：接受 Context Store 并扫描 API 端点。所需上下文包括 STACK（.NET 或 Python）和 PROJECT_ROOT（项目目录路径）。幂等性检查方面，.NET 会检索 AddSwaggerGen 或 UseSwagger，Python 检查 FastAPI 自定义配置；若已存在则返回 {"status": "skipped"}。API 分析包括扫描控制器/路由文件、识别认证方式（JWT、OAuth2、API Key）、检查 API 版本控制。
-
研究文档标准：使用 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 版本控制文档。
-
决策点：包括 API 信息（标题、版本为必填，描述、联系人、许可证为可选）、安全方案（JWT Bearer 推荐、API Key、OAuth2、None）、文档功能（XML 注释、响应示例、请求验证、Try It Out，默认均启用）。
-
生成配置：.NET 输出文件包括 Extensions/SwaggerExtensions.cs（Swagger 服务注册）和更新 *.csproj（启用 XML 文档）。生成过程使用 MCP ref 获取当前 Swashbuckle API，生成包含 AddEndpointsApiExplorer、AddSwaggerGen（含 OpenApiInfo）、安全定义（若检测到认证）、XML 注释包含的 SwaggerExtensions，并更新 csproj 以生成文档。需添加的包为 Swashbuckle.AspNetCore。注册代码为 builder.Services.AddSwaggerServices(); 和 app.UseSwaggerServices();。csproj 更新内容为 <PropertyGroup><GenerateDocumentationFile>true</GenerateDocumentationFile><NoWarn>$(NoWarn);1591</NoWarn></PropertyGroup>。Python 输出文件为 core/openapi_config.py（OpenAPI 自定义）。生成过程使用 MCP ref 获取 FastAPI OpenAPI 自定义，生成包含自定义 OpenAPI schema、安全方案定义、标签与描述的 openapi_config.py。FastAPI 自动生成 OpenAPI，此 worker 自定义默认配置。注册代码为 from core.openapi_config import custom_openapi 和 app.openapi = lambda: custom_openapi(app)。
-
验证：语法检查（.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。验证内容包括所有端点可见、请求/响应模式显示、安全方案显示（若配置）、Try It Out 可用。OpenAPI 规范验证命令：.NET 使用 curl http://localhost:5000/swagger/v1/swagger.json | jq .，Python 使用 curl http://localhost:5000/openapi.json | jq .。
使用方式
该技能作为 L3 Worker 运行，接收来自 ln-770 协调器的 Context Store，完成后返回结构化 JSON 响应给 ln-770 协调器，包含 status、files_created、packages_added、registration_code、message 等字段。
适用场景
适用于为 .NET 或 Python 后端项目添加交互式 API 文档，需要配置 Swagger/OpenAPI 时。
限制
关键规则包括：使用 MCP ref 获取当前 Swashbuckle/FastAPI API，不要凭记忆硬编码配置；自动检测认证方案（扫描 JWT、OAuth2 或 API Key 并相应配置安全定义）；在 .NET 中启用 XML 文档（更新 csproj 的 GenerateDocumentationFile 并抑制警告 1591）；FastAPI 为自定义而非替换（内置 OpenAPI 默认工作，仅添加自定义 schema/安全）；幂等性（若 AddSwaggerGen/UseSwagger 存在，返回 status: "skipped"）。完成定义包括：接收 Context Store（stack、project root）、分析 API 结构（控制器/路由、认证方式、版本控制）、通过 MCP 工具研究文档标准、生成含 API 信息与安全方案的 Swagger/OpenAPI 配置、启用 XML 注释（.NET）或配置自定义 OpenAPI schema（Python）、语法验证（dotnet build 或 py_compile）、返回结构化 JSON 响应给 ln-770 协调器。版本 2.0.0，最后更新 2026-01-10。