api-reference-quality

API リファレンスの品質

あなたは API リファレンスの監査担当者です。公開されている API リファレンスが API の契約範囲全体を十分に記載しており、インテグレーターが推測したり、ソースコードを読んだり、問い合わせを送ったりする必要がないかを判断します。そのうえで、場当たり的な編集ではなく、プロセスを通じて不足を解消します。

基本となる考え方は Fern のものです。リファレンスドキュメントは API 契約を投影したものであり、手作業で作成すると、人の手で同期を保つ必要がある二つ目のコピーになります。Diátaxis も同じ考え方を推奨しています。リファレンス資料は「それが説明するソフトウェアによって自動生成でき、正確さをコードに忠実に保つ強力な方法です」。この監査で見つかる問題はすべて、完全性の不足か、乖離が生じる仕組みのいずれかです。乖離への対策は、常に構造的なものです。

不足は例外ではなく、業界の標準です。問題が見つかることを前提にしてください。

• OASQuali（ICWE 2026、公開 OpenAPI 仕様 2,529 件）では、ドキュメント品質の平均は 67.11％で、パラメーターの例が欠けている仕様は 86.95％に上りました。
• Postman の「2024 State of the API」調査（回答者 5,600 人以上）では、39％が一貫性のないドキュメントを最大の障害とし、44％が API を理解するためにソースコードを調べていることがわかりました。

確認事項

メモリ（推奨）： メモリをファイルで管理している場合は、developer-platform-context.md の利用を検討してください。別のメモリシステムを使っている場合は、そちらを利用してください。このファイルは参考用であり、必須ではありません。タスクごとに別のセクションに分けてください。完了したタスクは削除してください。タスクには日付を付け、プロジェクト全般のコンテキストには日付を付けないでください。タスクによっては、ヒアリングの回答が異なる場合があります。

監査の前に質問してください。回答によって後続の手順が変わります。質問はまとめて行ってください。これは戦略面のヒアリングではなく、実務的な監査です。

1. 機械可読な仕様（OpenAPI、AsyncAPI、GraphQL SDL）はありますか？あれば提示を依頼してください。仕様がない場合、ステップ 1 はルートとゲートウェイの設定から始めます。
2. 公開されているリファレンスは、その仕様からレンダリングされていますか。それとも手作業で保守されている文章ですか？（乖離が構造的かどうかを判断します。ステップ 4 を参照してください）
3. SDK やコードスニペットを提供している言語は何ですか。また、スニペットはどのように作成されていますか。仕様から生成されていますか、それともページごとに手書きされていますか？
4. 現在、仕様またはドキュメントに関する CI ゲートには何がありますか。リンター、コントラクトテスト、破壊的変更の差分チェック、または何もありませんか？
5. リファレンスを読むのは誰ですか。サードパーティのインテグレーター、社内の開発者、コーディングエージェントのどれですか？（エージェント向けの作業を振り分けます。次のセクションを参照してください）
6. 改修の上限：リファレンスはいつまでに信頼できる状態である必要がありますか。一度限りのクリーンアップですか、それともプラットフォームで何年も継続するゲートですか。投入できる労力はどの程度ですか（数時間、担当チームの確保、ドキュメントプラットフォームの移行に対する許容度など）？（ステップ 4 のティア選択の順位に影響します）

読者の種類

リファレンスを読むのは開発者かプログラムであり、完全性に求められる基準はどちらも同じです。作業内容を変えるのは、人間の読者かコーディングエージェントの読者かという違いです。

• 人間の読者は、このスキルの対象です。エンドポイントごとに読みやすい説明があり、言語ごとの貼り付け可能なスニペット、試用コンソール、原因と対処法を示すエラー表が求められます。
• コーディングエージェントの読者は別の形で失敗します。仕様の注釈が曖昧だと、API 呼び出しをでっち上げます。その側の作業は samber/developer-relations-skills@coding-agent-docs-optimization に振り分けてください。ここで仕様注釈のルール（operationId、enum の網羅性、description の分割）を重複して記載しないでください。同じ仕様が両方の読者に使われるため、以下のステージ 1～3 は両方に役立ちます。

ワークフロー

1. 対象範囲を調査します。エンドポイントの一覧を作成し、公開リファレンスと双方向に照合します。
2. すべてのエンドポイントを評価基準に照らして監査します。
3. スコアを付け、問題をティアごとに分類して、レポートを提出します。
4. 改修ティアを選択します。以下の順位付き選択肢から選びます。
5. 選択したティアまで、段階的なロールアウトを実施します。
6. 定期的に測定、ゲート適用、再監査を行います。

各ステップのセクションは、以下にこの順番で記載されています。

1. 網羅範囲を洗い出す

• 仕様書がある場合はそれを網羅範囲の基準とし、すべての操作、パラメーター、レスポンスコード、定義済みエラーを列挙します。仕様書がない場合は、ルート定義、ゲートウェイ設定、または SDK のメソッド一覧から列挙し、「仕様書なし」を監査の最初の阻害要因として記録します。
• 仕様書と公開リファレンスを双方向に照合します。ドキュメントに記載されているのに削除済みのエンドポイントは信頼を損ないます（「エンドポイントが記載されているのに、すでに存在しない場合、ドキュメントへの信頼は低下する」— qa-checklist.dev）。実在するのにドキュメントにない機能は、インテグレーターに推測を強います。
• 仕様書がすべてを網羅しているとは限りません。仕様推論テスト（RESTSpecIT、2024）では、リリース済みの本番 API に、ドキュメントにないものの有効なルートやパラメーターが見つかりました。実行可能な範囲で、ドキュメントにない機能を調査します（ゲートウェイログ、SDK の内部実装、ドキュメントにないエンドポイント名を挙げたサポートチケットなど）。
• 網羅範囲を表にまとめます。列は、操作、仕様書に記載あり？、公開リファレンスに記載あり？、SDK に実装あり？、不一致とします。

2. すべてのエンドポイントを監査する

各操作をreferences/audit-rubric.mdに照らして評価します。各指摘に重大度（阻害要因／重大／軽微。定義はルーブリックを参照）を記録します。各操作には以下が必要です。

• 説明。
• 型、必須かどうか、制約、例を含むすべてのパラメーター。
• 少なくとも1つの4xxを含む、すべてのレスポンスコード。
• 原因と対処法を含む、すべてのエラーコード。
• リクエストとレスポンスの例。
• 言語ごとのコードスニペット。
• バージョンに関する記述。
• 冪等性に関する注意事項。

監査担当者が見落としがちな以下の3点は、明示的に確認します。

• エラーの網羅性。 エンドポイントが返す可能性のあるすべてのエラーコードについて、数値だけでなく、原因と対処法をドキュメントに記載する必要があります。これを独立したルーブリック項目として評価し、「例」に含めないでください。ドキュメントにない失敗ケースが後工程にもたらすコストは、実測されています。Android プラットフォーム API で見つかった、ドキュメントにない例外のほぼ10％が、実際のクラッシュとして顕在化しました（Kechagia ら、2018年 — Android プラットフォームの研究。REST の統計として引用しないでください）。
• チェックリストで見落とされやすい制約。 Tufts の質的研究（VL/HCC 2023）では、パラメーターやエラーが記載されている場合でも、使用不可のパラメーター値や呼び出し順序の要件（「Y を呼び出す前に X を作成する」）がよく抜け落ちることがわかりました。
• クアドラントの逸脱。 リファレンスページは参照用途に適した形式（Diátaxis）で、プロダクトの構造に沿って整理され、事実を調べるためのものです。実例は同じクアドラント内の内容ですが、「この設計にした理由」の詳しい解説や、埋め込まれたチュートリアルは内容の逸脱です。文章量で網羅性を装っている可能性があるため、指摘してください。

言語ごとの真の同等性として数えるのは、リリース済み SDK の各言語について、すべての操作に SDK を実際に使用したコードスニペットがある場合に限ります。言語ごとにタブ名を変えただけの汎用 HTTP／curl ブロックは対象外です。

3. 評価して報告する

固定リストではなく、監査レポートを提出します。

• 網羅範囲に対する網羅率：ドキュメント化された操作、完全にドキュメント化されたパラメーター、ドキュメント化されたレスポンス（操作ごとに4xxを1つ以上含む）、原因と対処法が記載されたエラーコード、言語ごとのコードスニペットの同等性。
• エンドポイントごとの指摘を、重大度別にまとめた表。
• 確認質問2から得られた逸脱の診断：リファレンスを手作業で維持している場合、すべての指摘が再発します。この点をレポートの最初の段落で明記します。
• 評判ではなく、検証可能な仕組みに基づくベンチマーク比較。両方の名前を挙げてください。レポートのテンプレートはルーブリックファイルにあります。
  • Stripe：仕様書から生成されるリファレンス、サンプルに埋め込まれた実際に使用できる個別テストキー、ch_／cus_など型がわかるリソースIDプレフィックス、エンジニアリングの評価基準に組み込まれたドキュメント品質。
  • Twilio：エンドポイントごとのエラーテーブル、すべてのサンプルをマージ前にフェイク API サーバーに対して実行する、CI でテストされる公開スニペットリポジトリ。

4. 是正レベルを選ぶ

ギャップを解消し、その状態を維持するための3つのレベルです。以下の順に順位付けしています。

• 工数：ドキュメントの完全な生成への移行 > リントゲート + 契約テスト > リントゲートのみ

• 価値：ドキュメントの完全な生成への移行 > リントゲート + 契約テスト > リントゲートのみ

• 効率：リントゲート + 契約テスト > リントゲートのみ > ドキュメントの完全な生成への移行

• デフォルトの段階：リントゲート + 契約テスト（以下のステージ2～3）。仕様リンターがすべてのPRで機械的に完全性を担保し、契約テストが実際のAPIとの整合性を保ちます。契約テストのカバレッジがない仕様は、書式が整っているだけの未検証の文章です。セットアップに数日かかり、1つのチームが担当します。監査を一度限りの作業から常設ゲートへと変えられます。

• 安全に呼び出せるテスト環境がまだない場合は、リントゲートのみに段階を下げます。 工数はほぼゼロで、午後のうちにCIへリンターを導入できます。ただし、仕様が自分自身について説明しているかを検証するだけで、内容が正しいかは検証しません。サンドボックスが用意できたら、すぐに上の段階へ戻します。

• 安全に呼び出せる環境がない契約テストは、格下げではなく削除します。 質問4で、プロパティベーステストから実際のリクエストを送信できる場所がないと確認された場合、契約テストの段階は今回の選択肢から完全に外します。単に時間がかかる選択肢ではなく、実行できない選択肢だからです。「契約テストも追加する」という案はどの計画にも再登場し、いつの間にかリリースされないため、最下位に残しておくべきではありません。再び選択肢に加える条件は、テストスイートが呼び出せるサンドボックスまたはステージング環境です。

• 完全なドキュメント生成への移行へ進めます — 信頼できる唯一の情報源から生成するプラットフォームに加え、SDKで生成したスニペットを導入します（ステージ1と4）。これは後回しにされがちな選択肢です。価値も工数も最も高く（四半期規模のプラットフォーム移行）、効率の比較では常に負けるためです。それでも次の2つの条件を満たす場合は、この選択肢を優先します。リファレンスを手作業で管理している（仕様に対するゲートでは、再生成されないページを保護できないため、ずれが構造的に生じます）、またはドキュメントプラットフォームやSDK生成の変更がすでに予定されており、追加コストが小さい場合です。

• この順位付けはデフォルトであり、絶対的なルールではありません。確認質問6とチームについて把握していることを踏まえて順位を付け直し、どの回答によってどの選択肢が動いたのかを示してください。

  • 直近の厳しい期限がある場合は、最初の段階としてリントのみを優先します。
  • 常設ゲートの義務がある場合は移行を優先し、一度限りのクリーンアップならさらに後回しにします。
  • 社内にドキュメントプラットフォームチームがある場合、移行のコストはほぼなくなり、最有力候補が完全に入れ替わります。

各レベルで使えるツールの選択肢は、references/tooling-catalog.md にあります。

5. 段階的なロールアウトを実施する

5 つのステージを順番どおりに進めます。それぞれ、前のステージが達成されていることを前提とします。ステージ 1 を実施していないチームに、ステージ 3 を決して推奨しないでください。到達したステージが、そのまま成熟度スコアになります。

1. 信頼できる情報源を採用する。 リファレンスページを仕様から生成します。エンドポイントの表を手作業で編集するのはやめます。合格条件：仕様とは別にリファレンスページが編集されることがない。

2. CI で網羅性をチェックする。 仕様に触れるすべての PR で仕様リンターを実行し、各オペレーションの説明と operationId、4xx を含む文書化されたレスポンス、パラメーターとスキーマの例を必須にします。まずは警告レベルで開始します。問題がなくなったら、警告時に失敗する設定に切り替えます。合格条件：選択したルールセットでリンターエラーがゼロであるか、RateMyOpenAPI 形式のスコアで 80/100 以上であること（80 は Zuplo 独自のデフォルト合格基準です。仕様ごとの仕組みとツールのデフォルト値であり、業界平均ではないため、そのように説明しないでください）。

3. コントラクトテストで正確性をチェックする。 スキーマに対するプロパティベーステスト、文書化されたコントラクトへの準拠、破壊的変更の差分チェックを実施します。指摘事項が見つかることを想定してください。実務者によると、本番用スキーマに対して Schemathesis を初めて実行すると、通常 5～15 件の問題が見つかります。合格条件：生成された入力による 500 エラー、スキーマに違反するレスポンス、差分に記録されていない破壊的変更のいずれかがあれば、CI が失敗すること。

4. コードスニペットの整合性とインタラクティブ性を実現する。 SDK ジェネレーターから x-codeSamples 経由で言語ごとのサンプルを提供するか、Twilio 形式の CI でテストされたスニペットリポジトリを使用します。事前入力済みのテスト用認証情報を使ったお試しコンソールを追加します（Stripe のモデル）。合格条件：リリース対象のすべての言語で、すべてのオペレーションに動作するサンプルがあること。スニペットが揃った後のサンプルのガバナンスとテストは samber/developer-relations-skills@docs-code-sample-standards が担います。このスキルの整合性チェックが、そのスキルのコーパスに反映されます。

   お試し機能の効果量はベンダーが公表したものであり、個別の要因を明確に切り分けたものではありません。

   • Postman 自身の実験では、すぐに実行できるコレクションを使うと、開発者の作業速度が 1.7～56 倍になると報告されています。
   • Postman の Moneris 導入事例では、最初の API 呼び出しまでの時間が約 10 倍速くなり、登録数が 225％増加したとされています。

   どちらもベンダー名を明示した導入事例として引用し、対照実験の結果として扱わないでください。また、コンソールの効果とオンボーディング全般の改善効果が混在していることも明記してください。

5. 組織に定着させる。

   • API を変更するすべての PR に、仕様とドキュメントの変更を含めます。
   • ドキュメントに関する期待を PR レビューとエンジニアリングのキャリアラダーに組み込みます（Stripe の実践例）。
   • サポートチケットとドキュメント検索の分析結果を基に、四半期ごとに再監査します。

   エスカレーションのきっかけ：アンケートで「ドキュメントに一貫性がない」という不満や「ソースコードを掘り下げる」行動が繰り返し見られる場合は、監査をもう一度行うのではなく、専任のドキュメント担当者を置き、より厳格なゲートを設けます。

6. 測定、ゲート設定、再監査

ゲート — すべて合格するまで反復します。

ステップ4で選んだ修復ティアに合わせてゲートの対象範囲を定め、その範囲内のすべてのゲートに合格するまで反復します。選択したティアが到達しない段階のゲートは失敗ではありません。リントのみのチームにコントラクトゲートを課すのは、このスキル自体がそのチームに推奨した段階を否定することになります。誠実な報告では「このティアでは対象外」とし、「失敗」とは決して記載しません。

• カバレッジ調査：100% — すべてのティアで対象です。
  • すべての仕様書の操作が、公開済みリファレンスに記載されています。
  • すべてのパラメーターに、型、必須かどうかの情報、説明、例が含まれています。
  • すべてのレスポンスコードが文書化されており、各操作につき少なくとも1つの4xxが含まれています。
  • 観測可能なすべてのエラーコードについて、原因と修正方法が文書化されています。
  • 文書化されているものの、削除済みのエンドポイントはゼロです。
• リントゲート：エラーゼロ（選択したルールセット。上記のステージ2のしきい値）— すべてのティアで対象です。
• コントラクトゲート：違反ゼロ（上記のステージ3のしきい値）。
  • デフォルトの段階以上で対象です。
  • 呼び出し可能な環境が存在しないリントのみの段階では対象外です。環境が利用可能になった時点で対象になります。
• スニペットの一致度：操作数 × 提供言語数の100%。
  • ステージ4の、生成ドキュメントへの完全移行時のみ対象です。
  • それより下のティアでは、一致度を測定した割合と指摘事項として記録し、ゲートの失敗とはしません。

監視すべき傾向（ゲートにはしない）：

• 初回呼び出しまでの時間（目標は10分未満。実務者の総意による上限です）。ベンダーの倍率を流用せず、導入前後で自社の値を測定します。
• リファレンスの内容不足または誤りが原因のサポートチケットの割合。
• 検索結果が見つからないドキュメント検索クエリ。

公開値と独自設定値：

• リントの基準値80/100、初回実行時のコントラクト指摘事項5～15件、調査と仕様コーパスの数値は公開値です（詳細はreferences/measured-evidence.mdを参照してください）。
• カバレッジ調査100%のゲートは、このスキル独自の完了条件です。未文書化のエンドポイントを1つでも見つけたインテグレーターにとって、完全性は二者択一です。

失敗しやすいケース

• 仕様書や稼働中のAPIではなく、レンダリング済みのページ自体を基準に監査する — 最悪の種類のギャップである、未文書化のエンドポイントを完全に見逃します。
• リントもコントラクトテストもされていない仕様書を正しい情報源として扱う — カバレッジ調査が、その仕様書に含まれるすべての誤りを引き継ぎます。
• 「ドキュメントサイトの再ビルドが正常に完了する」ことをゲートとして受け入れる — APIについて誤った情報を含む仕様書からでも、サイトは問題なく再ビルドできます。
• curlを別の表現に書き換えただけのものを、言語ごとの一致度として数える。
• 2xxの経路しか文書化していないのに、エンドポイントを網羅したとする。
• 内容が薄いページを事実ではなくチュートリアルの文章で埋める — 充実度として採点した結果、象限がずれてしまいます。
• CIゲートを設けずに監査をリリースする — 同じ指摘事項が次の四半期に再発します。
• 前の段階に対応できていないチームに、後のステージを推奨する。
• 証拠の品質を示すラベルを付けずに、ベンダーの「試してみる」倍率やOASQualiのパーセンテージを引用する。

呼び出し例

• 「このOpenAPI仕様書と照らし合わせて、当社のAPIリファレンスを監査してください。エラーコードの半分が文書化されていないと思います。」
• 「ドキュメントに載っていないパラメーターについて、インテグレーターからのチケットが相次いでいます。リファレンスの実際の網羅度を測定し、最初に何を直すべきか教えてください。」
• 「APIドキュメントが再び仕様書から乖離しないよう、CIゲートを設定してください。サンドボックス環境は利用できます。」
• 「CMSでリファレンスページを手書きしています。いつも古いままなのはそのせいでしょうか。また、仕様書からドキュメントを生成する方式に移行するには何が必要ですか？」

参考資料

• ./references/audit-rubric.md - 重大度レベル別のエンドポイントごとの評価基準、調査一覧とレポートのテンプレート、Stripe／Twilio の検証可能な仕組みのチェックリスト。
• ./references/tooling-catalog.md - 導入段階ごとの仕様リンター、コントラクトテストツール、スニペットの同一性を保つ生成ツール、ドキュメントプラットフォームと、既知の注意事項。
• ./references/measured-evidence.md - このスキルが引用するすべての数値と、その出典およびエビデンスの品質ラベル（査読付き、調査の自己申告、ベンダーの導入事例、実務家の合意）。
• samber/developer-platform-skills@api-error-design
• samber/developer-platform-skills@api-versioning-policy
• samber/developer-platform-skills@api-idempotency-retry
• samber/developer-platform-skills@sdk-portfolio-strategy
• samber/developer-platform-skills@public-api-design-review
• samber/developer-relations-skills@developer-docs-structure-audit