api-docs-writer

API ドキュメント作成スキル

このスキルは、生の API 仕様、エンドポイントの説明、または Postman コレクションを、OpenAPI に準じた慣例に従って、開発者向けの分かりやすいドキュメントに変換します。出力は、開発者ポータル、README、Notion／Confluence ページにそのまま使用できます。

必要な入力

与えられた情報をもとに作業してください。以下のいずれかが欠けている場合でも、完全な出力を作成してください。不足分には妥当な仮定を (仮定、要確認) と記して補い、最後にその仮定を一覧にしてください。コアとなる題材そのものが欠けている（書く内容がない）場合に限り、先に質問してください。

• API またはエンドポイントの詳細（生の仕様、Postman エクスポート、または口頭での説明）
• 認証方式（API キー／Bearer トークン／OAuth 2.0／なし）
• ベース URL
• API バージョン（例：v1、v2.3、または「バージョンなし」— 非推奨に関する注記やバージョンヘッダーに影響します）
• レート制限（既知の場合は、トークンまたは IP あたりの秒間／分間リクエスト数。不明の場合は「不明」）
• 対象読者（社内開発者／外部パートナー／一般公開）
• 出力形式（開発者ポータルおよび README 用の Markdown／Confluence または Notion 用のプレーンテキスト — 注：このスキルでは OpenAPI YAML は生成しません）

出力形式

各エンドポイントについて、以下を作成してください。

---

[METHOD] /path/to/endpoint

概要： [このエンドポイントの機能を1行で記述]

説明： [2～4文。このエンドポイントを使用する場面、返される内容、把握しておくべき重要な動作（ページネーション、レート制限、非同期処理など）を記述]

認証： [必須／任意 — 方式]

---

リクエスト

ヘッダー：

ヘッダー	必須	説明
Authorization	はい	Bearer <token>
Content-Type	はい	application/json

パスパラメーター：

パラメーター	型	必須	説明
id	string	はい	リソースの一意の識別子

クエリパラメーター：

パラメーター	型	必須	デフォルト	説明
limit	integer	いいえ	20	1ページあたりの最大結果数（1～100）
cursor	string	いいえ	—	前回のレスポンスから取得したページネーションカーソル

リクエストボディ：

{
  "field_name": "value",
  "another_field": 42
}

フィールド	型	必須	説明
field_name	string	はい	[このフィールドの機能を分かりやすく説明]
another_field	integer	いいえ	[説明。該当する場合は有効な範囲または列挙値を記載]

---

レスポンス

成功レスポンス：200 OK

{
  "id": "abc123",
  "status": "active",
  "created_at": "2025-04-01T10:00:00Z"
}

フィールド	型	説明
id	string	作成または取得されたリソースの一意の識別子
status	string	現在のステータス。列挙値：active、inactive、pending
created_at	ISO 8601 string	作成日時を示す UTC タイムスタンプ

---

エラーコード

ステータスコード	エラーコード	説明	解決方法
400	INVALID_REQUEST	リクエストボディの形式が正しくないか、必須フィールドがありません	上記のスキーマに照らしてリクエストボディを確認してください
401	UNAUTHORIZED	認証トークンがないか、無効です	API キーを確認するか、トークンを更新してください
404	NOT_FOUND	リクエストされたリソースが存在しません	パスパラメーターの ID を確認してください
429	RATE_LIMITED	リクエストが多すぎます	リクエストを控え、Retry-After ヘッダーの値に従って再試行してください
500	INTERNAL_ERROR	予期しないサーバーエラーです	指数バックオフで再試行してください。解決しない場合はサポートにお問い合わせください

---

コード例

対象読者に適した言語で、少なくとも2つの例を作成してください（デフォルト：cURL + Python）。

cURL：

curl -X POST https://api.example.com/v1/endpoint \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"field_name": "value"}'

Python：

import requests

response = requests.post(
    "https://api.example.com/v1/endpoint",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={"field_name": "value"}
)
data = response.json()

---

詳細資料

このスキルにはサポートファイルが付属しています。利用可能な場合は、次のファイルを使用してください。

• references/example-first-docs.md — 例を先に示す API ドキュメント：使いやすいドキュメントを作るルール。出力を作成する際に適用してください。上記の手法の概要で簡略化されている、調整基準や判断の指針が記載されています。
• templates/endpoint-entry.md — 品質ゲートがインラインで記載された、成果物の記入用テンプレート。生成を任せるのではなく、ユーザー自身でドキュメントを作成したい場合に提供してください。

評価基準（0～40）

このスキルの出力は、提出前に必ず評価してください。32 点以上が公開可能な品質です。

項目	0	5	10
パラメーターの網羅性	型や必須／任意の区別を示さずにフィールドを列挙している	表は完全だが、説明がフィールドの「内容」にとどまり、動作を説明していない。列挙値や範囲も記載されていない	すべてのフィールドに型と制約（列挙値、範囲、形式）があり、動作とその影響を説明している
エラーパスの網羅性	正常系のみで、エラー表がない	標準的な 400／401／404／429／500 の行はあるが、解決方法の説明がない	標準的なエラーに加え、エンドポイント固有のコードも網羅し、再試行が安全でない場合を含め、開発者が行うべきことをそれぞれ説明している
サンプルの実行可能性	擬似コード、未定義の変数、または「YOUR_ENDPOINT」のようなプレースホルダーを使用している	サンプルはあるが、そのままコピーして実行できない、または 1 つの言語しか使っていない	2 つ以上の言語を使用し、実際のベース URL と明らかに架空のプレースホルダー認証情報を使い、そのまま実行できる
動作に関する率直さ	非同期動作、ページネーション、べき等性、レガシーな挙動について記載がない	挙動上の注意点を文章では説明しているが、サンプルやエラー行には反映されていない	扱いにくいレガシーな挙動も含め、注意点と、それによって生成される正確なリクエスト／レスポンスを記載している

品質チェック

• すべてのパラメーターを文書化している（型、必須／任意、説明）
• レスポンスのフィールドを型も含めて完全に文書化している
• 関連するすべてのエラーコードを、解決方法の説明とともに列挙している
• エラーコードには最低限、400（不正なリクエスト）、401／403（認証）、404（見つからない）、429（レート制限）、500（サーバーエラー）が含まれている。または、エンドポイントに該当しないコードを明記している
• コード例では実際のベース URL と現実的なプレースホルダートークンを使用している。未定義の変数や「YOUR_ENDPOINT」をコードスニペットの外で参照する例はない
• 認証方式を冒頭で明確に示している
• 該当する場合、列挙値を記載している
• リストエンドポイントの場合、ページネーションについて説明している

アンチパターン

• 正常系だけを文書化しないでください。すべてのエンドポイントで、少なくとも 400、401／403、404、429、500 のエラーコードを記載する必要があります
• コード例で「YOUR_ENDPOINT」や「INSERT_TOKEN」のようなプレースホルダー値を使用しないでください。実際のベース URL に基づいた、現実的な見た目のプレースホルダーを使用してください
• 受け付ける値が固定されているフィールドでは、列挙値を省略しないでください。列挙値の記載漏れは、連携時の不具合につながります
• リストエンドポイントでページネーションの説明を省略しないでください。これを見落とした開発者は、データを気づかないまま取りこぼす連携を構築してしまいます
• フィールドが「何であるか」だけを説明し、「何をするか」を説明しないのは避けてください。「ID」だけではドキュメントになりません。「このリソースの取得や更新に使う一意の識別子」のように説明してください

使用例

• 「この API エンドポイントを文書化してください：[仕様または説明を貼り付け]」
• 「この Postman コレクションを開発者向けドキュメントにしてください」
• 「[エンドポイント] の API リファレンスドキュメントを書いてください」
• 「[製品] API の開発者向けガイドを書いてください」

トリガーフレーズの例

• 「API エンドポイントを文書化してください。」
• 「API リファレンスドキュメントを書いてください。」
• 「開発者向けガイドを作成してください。」
• 「生の仕様書／Postman コレクションをドキュメントにしてください。」