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 を Grep します
• 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
   • OpenApiInfo を含む AddSwaggerGen
   • セキュリティ定義（認証が検出された場合）
   • 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 のサポートが組み込まれています。このワーカーはデフォルト構成をカスタマイズします。

登録コード：

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 Specification

---

重要なルール

• 最新の Swashbuckle/FastAPI API には MCP ref を使用する — 記憶に頼って設定をハードコードしないでください
• 認証スキームを自動検出する — 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