api-doc-generator

このスキルの使い方

コードをスキャンして API エンドポイントを検出し、インターフェースの詳細を抽出して、標準化されたドキュメントを生成します。API やインターフェースに関する明示的な言及がない一般的なドキュメント作成の依頼では実行しないでください。

ワークフロー

1. コードをスキャン - 現在のプロジェクトまたは指定されたオブジェクトを確認し、Controller クラスと API インターフェースを探します
2. 情報を抽出 - インターフェースをスキャンして、リクエスト URL、メソッド、パラメーター、レスポンス情報を収集します
3. ドキュメントを生成 - 標準テンプレートに従って API ドキュメントを作成します
4. 出力を保存 - ドキュメントを現在のプロジェクトの ./docs ディレクトリに保存します

手順

ステップ 1：インターフェースをコードから探す

重要：ドキュメントを生成する前に、必ずコードをスキャンして API インターフェースを探してください。

1. 対象を特定する：

   • プロジェクト全体をスキャンするか、特定の Controller クラスをスキャンするか、ユーザーに確認します
   • 対象が指定されていない場合は、プロジェクト全体をスキャンして Controller クラスを探します
   • 一般的な Controller のパターン：
     • Java：@RestController、または @RequestMapping が付いた @Controller
     • Spring Boot：controller または web パッケージ内のクラス
     • Controller.java または Controller.kt で終わるファイル

2. Controller をスキャンする：

   • プロジェクト内で Controller クラスを検索します
   • @RestController または @Controller が付与されたすべてのクラスを特定します
   • 見つかった Controller クラスを一覧表示します

3. インターフェースを確認する：

   • 各 Controller クラスについて、以下のアノテーションが付与されたメソッドをスキャンします：
     • @GetMapping、@PostMapping、@PutMapping、@DeleteMapping
     • メソッドが指定された @RequestMapping
   • 見つかった API インターフェースの合計数を数えます

4. 検証する：

   • インターフェースが見つからない場合は、停止してユーザーに次のように伝えます：

     未找到任何接口，无法生成接口文档。请确认：
     1. 项目中是否存在 Controller 类
     2. Controller 类中是否有 @GetMapping、@PostMapping 等注解的方法
     3. 是否指定了正确的扫描路径
     

   • インターフェースが見つかった場合は、ステップ 2 に進みます

出力：Controller クラスの一覧と、見つかったインターフェースの合計数。

ステップ 2：インターフェース情報を抽出する

重要：各インターフェースについて、URL、メソッド、パラメーター、レスポンスを含む完全な情報を抽出してください。

見つかった各 API インターフェースについて、以下を抽出します：

1. 基本情報：

   • インターフェース名：メソッド名、またはアノテーションに記載された説明
   • リクエストメソッド：GET、POST、PUT、DELETE、PATCH
   • リクエスト URL：クラスレベルとメソッドレベルのマッピングを含む完全なパス
   • Controller クラス：パッケージを含む完全修飾クラス名
   • メソッド名：Java/Kotlin のメソッド名

2. リクエスト情報：

   • パスパラメーター：URL パス内のパラメーター（例：/user/{id}）
     • パラメーター名、型、必須フラグ、説明
   • クエリパラメーター：クエリー文字列内のパラメーター
     • パラメーター名、型、必須フラグ、デフォルト値、説明
   • リクエストボディ（POST/PUT の場合）：
     • ボディの種類（JSON、フォームデータなど）
     • フィールド定義：名前、型、必須フラグ、説明
     • ネストされたオブジェクトの構造
   • リクエストヘッダー：
     • 一般的なヘッダー：Authorization、Shop-Id、Tenant-Id
     • カスタムヘッダーがある場合はその内容

3. レスポンス情報：

   • レスポンス型：メソッドの戻り値の型
   • レスポンス構造：
     • 標準的なレスポンスラッパー（例：R<T>、ApiResponse<T>）
     • データオブジェクトの構造
   • レスポンスフィールド：
     • フィールド名、型、説明
     • ネストされたオブジェクトのフィールド
   • レスポンス例：JSON レスポンスの例を生成します
   • エラーレスポンス：一般的なエラーコードとメッセージ

4. 追加情報：

   • 説明：@ApiOperation、@Operation、またはメソッドコメントから取得
   • タグ：@Api、@Tag アノテーションから取得
   • 非推奨：@Deprecated アノテーションを確認
   • セキュリティ：認証・認可の要件

出力：抽出したすべての情報を含む、各インターフェースの構造化データ。

ステップ 3：ドキュメントの生成

重要：標準テンプレート形式に従ってドキュメントを生成してください。

1. テンプレートの言語を選択する：

   • ユーザーに希望する言語（中国語または英語）を尋ねます
   • 指定がない場合は、プロジェクトのコンテキスト（コードコメント、パッケージ名など）から判断します
   • 利用可能なテンプレート：
     • 中国語：templates/接口文档模板.md
     • 英語：templates/api-documentation-template-en.md

2. テンプレートを読み込む：

   • 言語の選択に基づいて適切なテンプレートを読み込みます
   • 基本構成として使用します

3. モジュールごとに整理する：

   • Controller クラスまたはビジネスモジュールごとにインターフェースをグループ化します
   • 各モジュールのセクションを作成します

4. インターフェース一覧表を作成する：

   • 中国語テンプレートの場合：「接口一览表」を作成し、次の列を含めます：
     • 序号（連番）
     • 接口地址（インターフェース URL）
     • 请求方式（リクエストメソッド）
     • 说明（説明）
     • 完成情况（ステータス）
   • 英語テンプレートの場合：「API Interface List」を作成し、次の列を含めます：
     • No.（連番）
     • Interface URL
     • Method
     • Description
     • Status

5. インターフェース定義を作成する： 各インターフェースについて、次の項目を生成します：

   • インターフェース名：明確で内容が分かる名前
   • インターフェースアドレス：メソッドを含む完全な URL
   • 説明：
     • 対応する Controller クラスとメソッド
     • ビジネス機能の説明
     • ビジネスルールがある場合はその説明
   • リクエストセクション：
     • メソッドと URL
     • ヘッダーテーブル
     • パスパラメーターテーブル
     • クエリパラメーターテーブル
     • リクエストボディ（該当する場合）とフィールド定義
   • レスポンスセクション：
     • レスポンス構造の説明
     • レスポンスフィールドテーブル
     • レスポンス例（JSON）
     • エラーレスポンスの例

6. 標準セクションを追加する：

   • 中国語テンプレートの場合：
     • 统一响应结构：標準レスポンス形式
     • 分页响应格式：ページネーションレスポンス形式
     • 错误码约定：エラーコードの規約
     • 请求头规范：リクエストヘッダーの仕様
     • 注意事项：重要な注意事項
   • 英語テンプレートの場合：
     • Standard Response Structure：標準レスポンス形式
     • Pagination Response Format：ページネーションレスポンス形式
     • Error Code Conventions：エラーコードの規約
     • Request Header Specifications：リクエストヘッダーの仕様
     • Important Notes：重要な注意事項

7. ドキュメントを整形する：

   • 適切な Markdown 形式を使用します
   • テーブルが正しく整形されていることを確認します
   • JSON の例にはコードブロックを含めます
   • 見出しの階層を適切に設定します

出力：Markdown 形式の完全な API ドキュメント。

ステップ 4：ドキュメントの保存

重要：現在のプロジェクトの ./docs ディレクトリにドキュメントを保存してください。

1. 出力パスを決定する：

   • デフォルト：./docs/api-documentation.md
   • 複数のモジュールがある場合：./docs/{module-name}-api-documentation.md
   • カスタムファイル名を希望するか、ユーザーに尋ねます

2. ディレクトリを作成する：

   • ./docs ディレクトリが存在するか確認します
   • 存在しない場合は自動的に作成します

3. ファイルを保存する：

   • 生成したドキュメントをファイルに書き込みます
   • UTF-8 エンコーディングを使用します
   • 適切な改行コードを使用します

4. ユーザーに通知する：

   • ファイルの保存先をユーザーに伝えます
   • ファイルパスを表示します
   • 必要に応じてドキュメントのプレビューを表示します

出力：ドキュメントファイルが ./docs/api-documentation.md（またはカスタムパス）に保存されます。

コードスキャンのガイドライン

Java/Spring Boot プロジェクト

コントローラーの特定：

• @RestController または @Controller が付与されたクラスを探します
• クラスレベルの @RequestMapping を確認します
• よく使われるパッケージパターン：*.controller.*、*.web.*、*.api.*

メソッドの特定：

• 次のアノテーションが付与されたメソッドを探します：
  • @GetMapping、@PostMapping、@PutMapping、@DeleteMapping、@PatchMapping
  • @RequestMapping(method = RequestMethod.GET) など

パラメーターの抽出：

• @PathVariable：パスパラメーター
• @RequestParam：クエリパラメーター
• @RequestBody：リクエストボディ
• @RequestHeader：リクエストヘッダー
• メソッドシグネチャからパラメーターの型を取得します

レスポンスの抽出：

• メソッドシグネチャから戻り値の型を取得します
• @ResponseBody アノテーション
• ジェネリック型（例：R<T>、Page<T>）
• レスポンスエンティティの構造

Kotlin/Spring Boot プロジェクト

Java と同様ですが、次の点を確認します：

• リクエスト／レスポンス用の Kotlin データクラス
• nullable 型（String?、Int?）
• Kotlin 固有のアノテーション

テンプレートと参考資料

• templates/接口文档模板.md - 中国語の API ドキュメントテンプレート
• templates/api-documentation-template-en.md - 英語の API ドキュメントテンプレート
• examples/scan-and-generate-example.md - ワークフロー全体の例

希望する言語（中国語／英語）をユーザーに尋ねます。指定されていない場合は、プロジェクトのコンテキストから判定します。

ベストプラクティス

1. コードのアノテーションやコメントから取得可能な情報をすべて抽出します
2. テンプレートの構成に厳密に従います
3. 適切な JSON 形式で、現実的なレスポンス例を含めます
4. よくあるエラーの状況とコードを記載します
5. インターフェースをモジュールまたは Controller クラスごとに整理します

キーワード

API ドキュメント、API ドキュメント、API ドキュメントの生成、インターフェースのスキャン、REST API、インターフェースドキュメント、API ドキュメント、インターフェースドキュメントの生成、インターフェースのスキャン