api-docs-quality-report

API Docs 監査スキル

ドキュメントサイト上のすべての API リファレンスエンドポイントページをクロールし、 各ページを 5 つの品質チェックで評価し、サイト全体の傾向を検出して、このセッションで 以前に生成された監査レポートのスタイルに合わせたインタラクティブな HTML レポートを出力します。

---

ステップ 0 — 入力の収集

必要な入力は 1 つだけです。ドキュメントの URL です。

ユーザーから URL が提供されていない場合は、次のように尋ねます。

監査する API ドキュメントの URL を教えてください。

URL が提供されている場合は、末尾のスラッシュを削除し、続行する前に確認します。

特別なケース —「X も同じように」： ユーザーが「同じように」または「X も同じ監査」と言った場合、新しい URL に対して同一のワークフローと HTML レポート形式を適用することを意味します。そのままステップ 1 に進みます。

---

ステップ 1 — すべてのエンドポイントページを検出

1a. まず llms.txt を試す

<docs_url>/llms.txt を取得します。

見つかった場合：

• パターン - [Page Title](URL): description に一致する行をすべて抽出します
• API リファレンスページのみを対象にします。次のいずれかを含むパスを探します。 api-reference、api-reference/、/api/、/endpoints/、/rest/、/docs/、/reference/、またはバージョン付きのパス（例：/v1/）
• 次のページは除外します：概要／インデックスページ（HTTP メソッドが示されていないもの）、SDK ドキュメント、CLI ドキュメント、 Terraform ドキュメント、ガイド、クイックスタートページ
• {title, url, description} のリストとして ENDPOINT_PAGES[] に保存します

見つからない場合、または 404 が返された場合：

• ドキュメントのホームページを取得します
• API／エンドポイントを参照しているナビゲーションサイドバーまたはサイトマップへのリンクを探します
• ナビゲーション構造から API リファレンスページの URL をすべて抽出します
• llms.txt を利用できなかったことをレポートに記載します

1b. カテゴリを特定

検出したページを URL パスのプレフィックスまたはナビゲーションのセクションごとにグループ化します。

• 例：/api-reference/agents/ → Agents カテゴリ
• 例：/api-reference/executions/ → Executions カテゴリ
• api-reference のルートレベルにあるページは Uncategorized に分類するか、タイトルから推測します

{name, page_count, pages[]} のリストとして CATEGORIES[] に保存します。

検出結果の概要を報告します。

K 個のカテゴリにわたって N 個のエンドポイントページが見つかりました。取得しています...

---

ステップ 2 — OpenAPI 仕様の有無を確認

個別のページを取得する前に、単独の OpenAPI 仕様が存在するかを確認します。

次の方法を順番に試し、最初に成功した時点で終了します。

1. ホームページまたはドキュメントのルートに対する Link HTTP ヘッダー（RFC 8288）を調べ、rel="openapi" または rel="describedby" がないか確認します。これは API 仕様の標準的な検出方法です
2. <docs_url>/openapi.json
3. <docs_url>/openapi.yaml
4. <docs_url>/api/openapi.json
5. llms.txt の「## OpenAPI Specs」に記載された URL

結果：

• アクセス可能な場合：SPEC_AVAILABLE = true とし、URL を保存します
• すべての試行で 404 が返され、Link ヘッダーも見つからない場合：SPEC_AVAILABLE = false

仕様がないこと自体が最優先の指摘事項です。問題 #1 として記録します。

---

ステップ 3 — すべてのエンドポイントページを取得して解析

ENDPOINT_PAGES[] 内の各 URL を取得します。ページごとに、次の項目を抽出します。

3a. ページレベルの説明文

OpenAPI ブロックの上に表示されるテキスト（または # タイトルから最初の ## OpenAPI 見出しまでのテキスト）です。これは人が記述した説明文です。

3b. OpenAPI ブロック

OpenAPI 仕様を含む、言語ヒントが yaml または json のフェンス付きコードブロックを探します。次の項目を抽出します。

• HTTP_METHOD — 例：GET、POST、PUT、DELETE、PATCH
• HTTP_PATH — 例：/api/v1/agents/{agent_id}/execute
• REQUEST_BODY_SCHEMA — requestBody のスキーマセクション（ある場合）
• PARAMETERS — パスパラメーターとクエリパラメーター（ある場合）
• RESPONSES — responses オブジェクト全体
• RESPONSE_200_SCHEMA — responses.200 または 201 の下にあるスキーマ

OpenAPI ブロックが見つからない場合は、SPEC_INLINE = false とします。

---

ステップ 4 — 各エンドポイントを評価（5 項目）

各エンドポイントについて、5 つのチェックすべてを評価します。結果は次の形式で保存します。 {check_name: "pass"|"warn"|"fail", current_state: string, fix_guidance: string}。

各チェックの正確な評価基準については、references/scoring-rules.md を参照してください。

チェック 1 — エンドポイントの説明 チェック 2 — OpenAPI 仕様 チェック 3 — ボディパラメーターの説明 チェック 4 — レスポンスコード チェック 5 — レスポンススキーマ

---

STEP 5 — サイト全体のパターンを検出する

すべてのエンドポイントのスコアを付けた後、多くのページで繰り返されるパターンを探します。

次の条件を満たすパターンを対象とします。エンドポイントの 60% 以上に影響します。

検出するパターン	特定方法
エラーコードが全体的に欠落	すべてのエンドポイントで 401、429、500 などが欠落している
レスポンススキーマが全体的に空	ほとんどのエンドポイントで schema: {} になっている
リクエストボディのスキーマが自由形式	ほとんどのリクエストボディで additionalProperties: true になっている
インライン仕様のみ／正規仕様が壊れている	すべてのページに仕様がインラインで埋め込まれているが、正規の仕様は 404 になる
説明が全体的に一言のみ	ほとんどのページで説明が 10 語未満
422 のみのバリデーションエラー	FastAPI の 422 のみが記載され、ビジネスエラーは記載されていない

検出した各パターンについて、次の内容をまとめた1 つの段落を作成します。

• パターンの内容
• 影響を受けるエンドポイント数
• 根本原因（例：FastAPI による自動生成、ミドルウェアのドキュメント不足）
• 開発者エクスペリエンスへの影響

SITE_WIDE_PATTERNS[] として保存します。

---

STEP 6 — 重要な問題をまとめる

すべての調査結果から、影響の大きい問題を上位 10 件まで順位付けします。次の優先順位に従います。

1. 最も多くのエンドポイントに影響する問題
2. トラフィック量が最も多い、または最も重要なエンドポイントに関する問題
3. セキュリティ上重要な欠落（認証エンドポイント、スキーマが空の認証情報エンドポイント）
4. 移行手段がない非推奨エンドポイント
5. 仕様の提供状況（正規仕様が 404 になると、すべての SDK ツールが利用できなくなる）

各問題について、次の内容を記載します。

• 簡潔な <strong>タイトル</strong>
• 特定のエンドポイント名または件数を含む、1～2 文の説明
• バッジ：FAIL または WARN

TOP_ISSUES[] として保存します（最大 10 件）。

---

STEP 7 — スコアカードを作成する

カテゴリごとに、次の値を計算します。

• total — エンドポイント数
• pass_count — 5 つのチェックすべてに合格したエンドポイント数
• warn_count — WARN が 1 つ以上あり、FAIL がないエンドポイント数
• fail_count — FAIL が 1 つ以上あるエンドポイント数

全体の合計を計算します。

SCORECARD[] として保存します。

---

STEP 8 — HTML レポートを生成する

references/html-template.md を読み、HTML の完全な構造、CSS 変数、 JavaScript、およびすべてのセクションのマークアップを確認します。

すべての {{VARIABLE}} プレースホルダーを実際の監査データに置き換えます。XSS を防ぐため、すべての値を HTML エスケープしてください。

主要な変数の対応表：

変数	入力元
{{DOCS_URL}}	入力 URL
{{AUDIT_DATE}}	今日の日付
{{TOTAL_ENDPOINTS}}	ENDPOINT_PAGES の件数
{{TOTAL_PASS}}	全カテゴリの pass_count の合計
{{TOTAL_WARN}}	warn_count の合計
{{TOTAL_FAIL}}	fail_count の合計
{{SPEC_COUNT}}	SPEC_AVAILABLE が true の場合は 1、それ以外は 0
{{SCORECARD_ROWS}}	SCORECARD から生成した <tr> 行
{{PATTERN_BOX}}	パターンボックスの HTML（SITE_WIDE_PATTERNS が見つかった場合）
{{TOP_ISSUES_HTML}}	TOP_ISSUES から生成した問題の行の HTML
{{SIDEBAR_LINKS}}	生成したサイドバーの <div class="sbl"> リンク
{{SECTIONS_HTML}}	各カテゴリのすべてのセクションの HTML

セクション HTML の生成ルールについては、references/html-template.md → Section: SECTIONS_HTML を参照してください。

ファイルの出力先：

/mnt/user-data/outputs/<slug>-api-audit-report.html

<slug> は、ドメイン名のピリオドをハイフンに置き換えたものです （例：docs.kubiya.ai → kubiya-ai）。

その後、present_files を呼び出してファイルを提供します。

---

エラー処理

状況	対応
llms.txt が 404 を返す	ホームページからナビゲーションリンクをクロールし、レポートに記載する
個別のエンドポイントページが 404 を返す	スキップし、フッターの「アクセスできないページ」の件数に加える
ページに OpenAPI ブロックがない	Spec チェックを FAIL として採点し、他のチェックは説明文に基づいて採点する
ページに説明文がない	Description を FAIL として採点し、「説明文なし」という注記を付ける
エンドポイントページが robots.txt によってブロックされている	レポートに記載し、取得しない
エンドポイントが 200 件を超える	バッチ取得し、20 件ずつ処理して進捗をユーザーに報告する
正規の仕様にアクセスできる	好ましい調査結果として記載し、問題として扱わない

してはいけないこと

• ❌ すべてのページを取得してスコアを付ける前に、HTML の生成を始めないでください
• ❌ エンドポイントのページを省略しないでください。llms.txt に記載されているすべてのページを取得してください
• ❌ ページタイトルだけからスコアを推測しないでください。実際のページ内容を取得してください
• ❌ 200 が記載されているというだけで、Response Codes を PASS にしないでください
• ❌ schema: {} に対して Response Schema を PASS にしないでください。これは FAIL です
• ❌ additionalProperties: true に対して Body Params を PASS にしないでください。最低でも WARN です
• ❌ パターンがエンドポイントの 60% 以上に影響していない限り、サイト全体に共通するパターンとして報告しないでください
• ❌ 汎用的な修正テキストを記載しないでください。すべての fix_guidance で具体的なエンドポイントに言及してください

---

参照ファイル

• references/scoring-rules.md — 5 つのチェックすべてに対する PASS／WARN／FAIL の正確な基準と、 詳細な例が記載されています。エンドポイントのスコアを付ける前に読んでください。

• references/html-template.md — すべてのセクションのマークアップ、変数マップ、レンダリング手順を含む、完全な HTML／CSS／JS テンプレートです。 HTML を作成する前に読んでください。