api-documentation

API ドキュメント

このスキルは、インテグレーターが最初の成功にたどり着き、リファレンスの正確な情報を理解し、API の進化に伴って行き詰まることなく利用できるよう支援する、開発者向け API ドキュメントの公開または更新が主な作業である場合に使用します。

api-documentation は、ドキュメント関連スキル群の中核となるスキルです。対象は次のとおりです。

• エンドポイント／スキーマのリファレンスドキュメント
• クイックスタートと最初の成功までの手順
• タスク指向のインテグレーションガイド
• SDK ガイド
• Webhook の配信／検証ドキュメント
• 開発者ポータルのナビゲーションと、グループ化されたリファレンスの表示領域
• ドキュメントの表示領域に関連する移行情報

モードや成果物一式を選ぶ前に、次のサポートドキュメントを読んでください。

• references/documentation-modes-and-boundaries.md
• references/output-packets-and-navigation.md
• references/example-and-reference-checklist.md
• references/publishing-and-drift-control.md

このスキルを使用する場合

• 外部の開発者、パートナー、または社内のインテグレーターが実際に利用できる API リファレンス、クイックスタート、ポータルページが必要な場合。
• OpenAPI またはスキーマの成果物はすでに存在するものの、ドキュメントに構成、例、認証／セットアップの説明、エラー処理、またはわかりやすいナビゲーションが必要な場合。
• 認証、バージョニング、リトライ、ページネーション、Webhook、または SDK の変更後に、既存の API ドキュメントが実態と乖離している場合。
• 公開 API、パートナー API、または社内 API のリリースに、開発者向けガイド、移行に関する注記、または信頼できる例が必要な場合。
• 大規模な API の情報をグループ化して選択的に公開したり、巨大なリファレンスを一括で掲載するのではなく、ポータルの構成を改善したりする必要がある場合。

このスキルを使用しない場合

• 主な作業がリソース、エンドポイントの形状、スキーマのルール、またはバージョニング戦略の設計である場合 → api-design を使用してください。
• 主な作業が社内仕様書、ADR、ランブック、ロールアウトドキュメント、またはシステム移行手順の作成である場合 → technical-writing を使用してください。
• 主な作業がエンドユーザー向けの製品 UI のオンボーディング、スクリーンショット、チュートリアル、またはヘルプセンターのドキュメントである場合 → technical-writing を使用してください。
• 主な作業が、API 利用者の認証方法を文書化することではなく、認証／セッション／プロバイダーの動作の実装である場合 → authentication-setup を使用してください。
• 主な作業がリリースノート、セマンティックバージョニング、または変更履歴の管理である場合 → changelog-maintenance を使用してください。
• API の動作について信頼できる情報源がまだ存在しない場合 → 直感だけでドキュメントを作成せず、不足している契約上の確認事項を api-design に戻してください。

手順

ステップ 1：API ドキュメントの作業を分類する

執筆を始める前に、依頼内容を整理します。

api_documentation_mode:
  primary_mode: reference | quickstart | task-guide | sdk-guide | webhook-guide | migration-update
  api_style: rest | graphql | webhook | sdk | mixed | unknown
  audience: external-developers | internal-integrators | partners | mixed | unknown
  source_of_truth: openapi | graphql-schema | code-annotations | tests | mixed | unknown
  docs_surface: developer-portal | docs-site | repo-markdown | sdk-site | internal-catalog | unknown
  navigation_scope: single-operation | grouped-resource | large-api-surface | portal-section | unknown
  maintenance_state: new-docs | refresh | drift-fix | launch-critical

実行ごとに主要モードを 1 つ選びます。

• reference → パラメーター、フィールド、エラー、制限、例を含むエンドポイント／スキーマの正確な情報
• quickstart → API 呼び出しの成功または Webhook 受信に至る最短の手順
• task-guide → 1 つのワークフローまたはインテグレーションの成果
• sdk-guide → 言語／クライアントライブラリのガイダンスと、例および注意事項
• webhook-guide → 配信、検証、リトライ、ローカルでのデバッグに関するガイダンス
• migration-update → 変更された動作と、ドキュメント上での移行手順

対象範囲が広い場合は、文章だけでなく、グループ化／ナビゲーションも課題に含まれるかどうかを判断します。広範囲な情報設計を、一般的な「ドキュメントを書く」という依頼の中に埋もれさせないでください。

Step 2: 対象範囲のスキルと開発者が実際に行う作業を確認する

執筆を始める前に、次の4つの質問に回答してください。

1. この API を統合するのは誰で、読了後に具体的にどの作業を完了できる必要がありますか？
2. 現時点で、契約の信頼できる唯一の情報源となる成果物は何ですか？
3. 更新するドキュメントの掲載先はどれですか？ポータル、リポジトリのドキュメント、SDK サイト、社内カタログ、または複数ですか？
4. 対象外とする必要がある、隣接するスキルはどれですか？

簡易振り分け表：

依頼内容が次のような場合	使用するもの
「コーディング前にエンドポイント／リソース／スキーマを設計する」	api-design
「アーキテクチャドキュメント／ADR／ロールアウト計画／運用手順書を作成する」	technical-writing
「製品 UI の使い方に関する顧客向けヘルプドキュメントを作成する」	technical-writing
「プロバイダーのセットアップ／セッションミドルウェア／トークンの実装について説明する」	authentication-setup
「リリースで提供された内容を要約する」	changelog-maintenance
「開発者ポータル／OpenAPI ドキュメント／クイックスタート／Webhook ガイドを作成する」	api-documentation

Step 3: 必要最小限の、信頼できる根拠を集める

古い仕様書だけをもとに API ドキュメントを書かないでください。まず、信頼できる根拠を必要最小限集めます。

• 現行の OpenAPI／GraphQL スキーマ／エンドポイント一覧／SDK の API サーフェス
• 認証要件：キー、ヘッダー、スコープ、署名、サンドボックスと本番環境の違い、コールバック／Webhook の検証
• 現在の動作に合致するリクエストとレスポンスの例
• よくあるエラー、再試行、制限、ページネーション／カーソルの動作、冪等性に関する想定
• バージョン管理、非推奨化、移行に関する注記
• 例の正確性を保つテスト、フィクスチャ、または検証済みリクエスト
• 公開に関する制約：ポータルのナビゲーション、選択的な公開の要件、ドキュメントサイトの構造、社内カタログのグループ分け

詳細が不足している場合は、想定を明確に記載し、確実であるかのように装うのではなく、ドキュメントの不足項目一覧を作成してください。

Step 4: 役に立つ最小限のドキュメント一式を選ぶ

開発者が行う作業に合わせて出力を選びます。デフォルトで、クイックスタート、リファレンス、SDK ドキュメント、移行に関する注記を1つの巨大なページに詰め込まないでください。

よくあるドキュメント一式：

• クイックスタートページ1つ
• グループ分けしたリファレンスセクション1つ
• タスク／統合ガイド1つ
• SDK ガイド1つ
• Webhook ガイド1つ
• 移行に関する更新情報1つ
• 未解決の情報源の問題に関する、ドキュメント不足／乖離チェックリスト1つ
• 大規模な API サーフェス向けの、ナビゲーション／グループ分けの提案1つ

モード別のひな形とポータル／グループ分けに関するガイダンスについては、references/output-packets-and-navigation.md を使用してください。

Step 5: 一般的な文章作成の助言ではなく、API ドキュメントのルールを適用する

次のルールを徹底してください。

• マーケティング文ではなく、開発者のタスクと統合対象を最初に示します。
• 認証と環境に関する前提を早い段階で明記します。
• 例の正確性を保ちます：テスト、検証済みリクエスト、または実際のフィクスチャの形式を優先してください。
• 運用上の実態を記載します：エラー、再試行、制限、ページネーション、Webhook の再送、結果整合性、冪等性。
• リファレンスとしての正確な情報と、ワークフローのガイダンスを分けます。
• 大規模な API ではナビゲーションに関する判断を明示します：グループ分け、選択的な公開、関連ガイドへのリンクが重要です。
• 意図を持って相互リンクを設定します：クイックスタートから詳細なリファレンスへ、リファレンスからタスクガイドへ、移行情報からは変更履歴／リリースノートへリンクし、移行情報で置き換えないでください。

Step 6: 乖離を意図的に防ぐ

最終化する前に、次の項目を記録してください。

• 契約の信頼できる唯一の情報源
• 例の信頼できる唯一の情報源
• 公開先
• レビューの実施条件
• 乖離しやすい箇所：認証、制限、再試行、バージョン管理、Webhook のフィールド、SDK の例、移行に関する注記
• 整合性を保つ必要がある関連ドキュメント：クイックスタート、SDK ページ、変更履歴の項目、Postman コレクション、ポータルのナビゲーション

乖離を防ぐためのチェックリストとして、references/publishing-and-drift-control.md を使用してください。

ステップ 7：出力品質を確認する

公開する前に、次の点を確認してください。

1. このドキュメント一式を使って、新しいインテグレーターが最初の成功にたどり着けますか？
2. 最初の呼び出しを行う前に、認証と環境に関する前提条件が明示されていますか？
3. 例は実際の動作と一致していますか？
4. 必要な箇所に、エラー、制限、再試行、ページネーション、検証に関する注意事項が記載されていますか？
5. 出力一式は、依頼に対して十分にコンパクトですか？
6. api-design、technical-writing、technical-writing、authentication-setup、changelog-maintenance への振り分けが、引き続き明示されていますか？

例

例 1：パートナー API のクイックスタート

入力：「パートナーが API キーを作成し、最初の POST /orders を送信して、返された注文 ID を検証できるように、Orders API のクイックスタートを作成してください。」

望ましい出力の形式：quickstart を選び、前提条件と認証を早い段階で示し、最初の成功につながるリクエストと成功確認を 1 つ提示して、より詳しいリファレンスへのリンクを含めます。

例 2：大規模なリファレンスの整理

入力：「開発者ポータルで巨大な OpenAPI コレクションを 1 つ公開しています。エンドポイントを整理し直し、パートナー向けのセクションだけを公開して、開発者が一覧できるナビゲーションを追加するのを手伝ってください。」

**望ましい出力の形式：**これを reference と navigation/grouping の作業として扱い、セクションのグループ化または選択的な公開を提案し、事実に即したリファレンスへのリンクを維持します。また、自動生成だけで構成の問題が解決するかのように装いません。

例 3：Webhook の変更通知

入力：「invoice.paid の再試行期間が 24 時間になり、attempt_count が含まれるようになり、配信ごとに HMAC 検証が必要になったため、Webhook ドキュメントを更新してください。」

望ましい出力の形式：webhook-guide または migration-update を選び、再試行と検証の動作を説明し、影響を受ける例を更新します。実装の詳細やリリースノートの整備は対象外とします。

例 4：API 設計への振り分け

入力：「これを REST にするか GraphQL にするか決まっておらず、リソースモデルとページネーションの計画が必要です。」

**望ましい出力の形式：**タスクを api-design に振り分け、ドキュメントを公開する前にコントラクト／インターフェースの作業が必要であることを説明し、後で必要になるドキュメントの種類に触れる場合もあります。

ベストプラクティス

1. API ドキュメントは、スキーマを表示するだけでなく、開発者のワークフローを支える成果物として扱います。
2. コントラクトの設計と、開発者向けの公開を分けます。
3. 巨大なポータルページを 1 つ作るより、内容が正確で小規模な出力一式を優先します。
4. 認証、例、制限、再試行、ページネーション、Webhook の動作を早い段階で明示します。
5. 大規模なドキュメントでは、ナビゲーション／グループ化の方針を本文に埋もれさせず、明確に記載します。
6. 更新内容が実際の情報源から逸れないように、ドキュメントのメンテナンスを信頼できる情報源と結び付けます。
7. 関連する執筆、認証の実装、リリース管理のタスクは、適切な隣接スキルに振り分けます。

参考資料

• OpenAPI Initiative
• Stripe API リファレンス
• GitHub REST API ドキュメント
• ReadMe ガイド
• Redocly ドキュメント
• Postman API ドキュメント