mcpField
A
api-design-expert

api-design-expert

github.com/shipshitdev開発38203 回インストール2 日前に更新
リポジトリ

api-design-expert について

API を新規作成・保守する開発者向けの設計ガイドスキルです。REST の規約、レスポンスとエラー形式、バージョニング、バリデーション、ドキュメント作成を扱います。

主な機能

  1. 01REST エンドポイント設計
  2. 02HTTP ステータスコードの指針
  3. 03レスポンスとエラー形式
  4. 04DTO バリデーションパターン
  5. 05バージョニングと OpenAPI の実践

活用シーン

  1. 01API エンドポイントの計画
  2. 02エラーレスポンスの標準化
  3. 03ページネーション付き API の設計
  4. 04OpenAPI による API 文書化

インストール

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

$npx skills add https://github.com/shipshitdev/skills --skill api-design-expert

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

同梱ファイルplugin.jsonreferences/full-guide.md

詳細

API 設計エキスパートスキル

使用する場面

  • 新しい API エンドポイントを設計するとき
  • RESTful API を作成するとき
  • OpenAPI/Swagger ドキュメントを作成するとき
  • API のバージョン管理を実装するとき
  • エラーレスポンスを設計するとき
  • DTO とバリデーションを作成するとき
  • ページネーション、フィルタリング、ソートを実装するとき

プロジェクトコンテキストの確認

ガイダンスを提供する前に、次の点を確認してください。

  1. API のパターンとアーキテクチャに関するメモを .agents/memory/ で確認します
  2. 既存のコントローラーと DTO を確認します
  3. OpenAPI/Swagger の設定を確認します
  4. バージョン管理の方針を確認します

基本原則

RESTful 設計
// Use nouns, plural, hierarchical
GET    /api/users
GET    /api/users/:id
POST   /api/users
PUT    /api/users/:id
DELETE /api/users/:id
GET    /api/users/:id/posts
HTTP ステータスコード
  • 200 OK / 201 Created / 204 No Content
  • 400 Bad Request / 401 Unauthorized / 403 Forbidden
  • 404 Not Found / 409 Conflict / 500 Internal Server Error
レスポンス形式
// Single resource
{ "data": {...}, "meta": {...} }

// List with pagination
{ "data": [...], "pagination": { "page", "limit", "total" } }
エラー形式
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [...],
    "timestamp": "...",
    "path": "/api/users"
  }
}

ベストプラクティス

  • 命名規則を一貫させます
  • すべての入力を DTO で検証します
  • OpenAPI/Swagger ドキュメントを用意します
  • すべてのエンドポイントに認証を適用します
  • リストにはページネーションを使用します
  • 最初から API のバージョン管理を行います

DTO の完全な例、ページネーション／フィルタリング／ソートのパターン、バージョン管理の方針、OpenAPI の設定、CRUD コントローラーのパターン、ネストされたリソース、一括操作、アンチパターンについては、次を参照してください。 references/full-guide.md

コメント

Markdown 対応