mcpField
D
document-api-endpoint

document-api-endpoint

github.com/getsentry開発1.1k1.2k 回インストール5 日前に更新
リポジトリ

document-api-endpoint について

Sentry のコードベースで drf-spectacular を使い、API エンドポイントのドキュメントと型を整備するスキルです。宣言したスキーマを実際のレスポンスに合わせ、旧ドキュメントを安全に移行します。

主な機能

  1. 01クラスおよびメソッドのスキーマデコレーター追加
  2. 02標準レスポンス型とサンプルの再利用
  3. 03実際のエンドポイント応答との型照合
  4. 04旧パスドキュメントの一括移行
  5. 05生成した API ドキュメントの検証

活用シーン

  1. 01Sentry API エンドポイントの新規ドキュメント作成
  2. 02実際の応答に合わせたレスポンス型の修正
  3. 03エンドポイントの PUBLIC への昇格

MCP 対応

エンドポイントを呼び出す MCP ツールで動作を確認できると説明しています。また、再生成された `sentry-api-schema` が SDK と MCP に反映される流れにも触れています。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/getsentry/skills --skill document-api-endpoint

インストール後、Claude Code で/document-api-endpointを入力して読み込まれたか確認します。

詳細

Sentry API エンドポイントのドキュメント作成と型定義

drf-spectacular を使って、Sentry エンドポイントの OpenAPI ドキュメントを追加または修正します。詳細なリファレンスは https://develop.sentry.dev/backend/api/public/ にあります。特に役立つのは https://develop.sentry.dev/backend/api/public/#5-method-decorator のセクションです。このスキルでは、そこに記載されている内容に加えて、わかりにくい点を説明します。作業の大部分は、宣言したスキーマをエンドポイントが実際に返す内容と一致させることです。ドキュメントを作成する前に、どのエンドポイントクラスがルートを処理し、何をするのかを確認してください。通常、その動作を確認するには、エンドポイントを呼び出す MCP ツールを使うのが最も手早い方法です。PRIVATE／EXPERIMENTAL エンドポイントを PUBLIC に昇格させるのも、応用例のひとつです（以下を参照）。

ワークフロー

  1. クラスレベルの @extend_schema(tags=[...]) — 既存の OPENAPI_TAGS エントリーのうち、最も近いものを使用します。
  2. メソッドレベルの @extend_schema(operation_id=..., parameters=[...], responses={...}, examples=...)。
  3. src/sentry/apidocs/parameters.py と examples/*.py を再利用し、owner = ApiOwner.<TEAM> が設定されていることを確認します。
  4. そのパスを対象とする旧形式の api-docs/paths/**/*.json がある場合は、削除します（レッスン 4 を参照）。
  5. 検証してから、実際のエンドポイントに対して確認します（レッスン 1 を参照）。

レッスン

1. コードの動作と宣言した型を注意深く比較する

できれば実際のトークンを使って実際のエンドポイントを呼び出し、キーと型を TypedDict と比較してください。シリアライザーが不正確な場合もあります。整数ではなく浮動小数点数として返される件数、int と宣言されている ID が文字列として出力されるケース、フィールド数の宣言が間違っている入れ子の型に注意してください。実行時の値に合わせて、宣言した型を修正します。

curl -s -H "Authorization: Bearer $TOKEN" "https://us.sentry.io/api/0/<endpoint>" | jq 'keys'
2. 正規のレスポンス型を再利用する

コードベースの XxxResponseOptional(TypedDict, total=False) ミックスインと一致させます（メインクラスで必須フィールドを宣言します）。null 許容とキーの省略の違いは次のとおりです。T | None はキーが常に存在し、値が null の場合があることを意味します。NotRequired[T] は、条件に応じてキーが設定されることを意味します（例：expand クエリパラメーター）。*_types.py に 2 つ目、3 つ目の定義を作るのではなく、既存の正規の型を再利用してください。再利用できる適切な正規の型がない場合（例：vroom／profiling など、別サービスからプロキシされるペイロード）は、新しいミラーを作るのではなく dict[str, Any] として型付けし、シリアライザーだけでなく、所有元のサービスのリポジトリで形状を確認してください。

3. 型を推論させる。cast と # type: ignore は避ける

シリアライザーが基本型と追加フィールドを返す場合は、型を強制するのではなく、レスポンス型が推論されるように生成側のコードをリファクタリングします。

4. 旧形式ドキュメントの移行はパス単位ですべて行う

api-docs/paths/**/*.json ファイルと、api-docs/openapi.json 内のその $ref を削除します。drf-spectacular の APPEND_PATHS は HTTP メソッドをマージしません。そのため、あるパスのいずれかのメソッドで @extend_schema を使うと、そのパスの旧形式のメソッドがすべて消えます。1 回のコミットで、そのパス上の全メソッドを移行してください。

PUBLIC への昇格

上記のワークフローを行ったうえで、具体的なエンドポイントのみ（同じパスの他のエンドポイントは PRIVATE のまま）に対して、次の操作を行います。

  • publish_status[<METHOD>] を PUBLIC に変更し、owner = ApiOwner.<TEAM> を設定します。
  • API_OWNERSHIP_ALLOWLIST_DONT_MODIFY からそのメソッドを、ステータス変更と同じ変更内で削除します。
  • エンドポイントが重複している場合、または名称を変更する場合は、まず別の変更で旧バージョンを削除または非推奨にし、その変更を基に公開設定の変更を重ねます。
  • スコープが広がる場合（event:read → event:{admin,read,write}）は、PR に記載してください。これは drf-spectacular が permission_classes から再生成したもので、ドキュメントのみの変更です。

下流の sentry-api-schema が再生成されて初めて、この変更が @sentry/api SDK／MCP に反映されます。

検証

make build-api-docs
pnpm run validate-api-examples
.venv/bin/pytest -q --reuse-db tests/apidocs/endpoints/<area>/test_<name>.py
.venv/bin/prek run -q --files <changed paths>

コメント

Markdown 対応