name: api-design-generator
description: >
RESTful API設計とOpenAPI 3.x仕様書を生成する。
Use when user asks to design APIs, create API documentation,
generate OpenAPI specs, review API endpoint design, or document existing APIs.
Avoid using for GraphQL schema design, WebSocket protocol design,
or general code documentation unrelated to APIs.
allowed-tools: "Bash(npx:*), Read, Write, Glob, Grep, Edit"
metadata:
author: "user"
version: "0.1.0"
category: "dev"
tags: ["api", "openapi", "rest", "design"]

API Design Generator

RESTful API設計とOpenAPI 3.x仕様書を自動生成するスキル。

目的 / Scope

成果

• RESTful設計原則に準拠したAPI設計
• OpenAPI 3.x YAML仕様書の生成
• 既存コードからのAPI仕様書抽出
• API設計のレビューと改善提案

対象外

• GraphQL スキーマ設計
• WebSocket プロトコル設計
• gRPC / Protocol Buffers 定義
• API実装コードの生成（設計のみ）

いつ起動するか（Trigger）

代表的なフレーズ

• 「APIを設計して」「エンドポイントを設計したい」「REST APIの構成を考えて」
• 「OpenAPI仕様書を作って」「Swagger定義を作成して」
• 「このAPIのドキュメントを生成して」「エンドポイントを文書化したい」
• 「API設計をレビューして」「REST設計を改善したい」

ネガティブトリガー（起動しない）

• 「GraphQL APIを設計して」→ GraphQL専用ツール
• 「WebSocketサーバーを作って」→ WebSocket実装
• 「APIを実装して」→ impl スキル
• 「コードのコメントを書いて」→ ドキュメントスキル

入力として必要な情報（Intake）

必須情報

任意情報（デフォルト値あり）

既存コードから生成する場合の確認

1. 「プロジェクトのフレームワークは何ですか？（Express, Next.js など）」
2. 「ルート定義があるファイルを教えてください」
3. 「既存の型定義はありますか？（TypeScriptの場合）」

実行手順（Workflow）

Step 0: 前提チェック

プロジェクト構造を確認し、既存APIの有無を判定。

1. package.json の有無確認 → フレームワーク判定
2. openapi.yaml, swagger.yaml の存在確認 → 既存仕様があれば「追記」か「新規作成」か確認
3. src/routes/, app/api/, pages/api/ の存在確認 → 既存コードの有無

使用ツール: Glob: **/package.json, **/openapi.yaml, **/routes/**

Step 1: 要件整理

1-1. リソースの特定

ユーザーからの情報をもとに、APIで扱うリソースを整理：

1-2. アクターと操作の整理

Step 2: リソース設計

RESTful命名規約に準拠したURL設計：

命名規約チェック:
- リソース名は複数形（/users, /products）
- kebab-case を使用（/order-items）
- ネストは最大2階層まで（/users/{id}/orders まで）
- 動詞を含めない（/getUsers は NG）

リレーションの表現:
- 親子関係が明確 → サブリソース（/users/{id}/orders）
- 多対多、複雑な条件 → クエリパラメータ（/orders?user_id={id}）

参照: references/rest-design-principles.md

Step 3: エンドポイント設計

HTTPメソッドとCRUDのマッピング

ステータスコードの選定

検索・フィルタリング

• フィルタ: ?role=admin, ?category=electronics
• ソート: ?sort=created_at, ?sort=-name（降順）
• ページネーション（offset-based）: ?offset=20&limit=10
• ページネーション（cursor-based）: ?cursor=abc123&limit=10

参照: references/openapi-patterns.md

Step 4: スキーマ設計

リクエストボディスキーマ

CreateUserRequest:
  type: object
  required:
    - name
    - email
  properties:
    name:
      type: string
      minLength: 1
      maxLength: 100
    email:
      type: string
      format: email
    role:
      type: string
      enum: [user, admin]
      default: user

レスポンスボディスキーマ

UserResponse:
  type: object
  properties:
    id:
      type: string
      format: uuid
    name:
      type: string
    email:
      type: string
      format: email
    created_at:
      type: string
      format: date-time

エラーレスポンススキーマ（RFC 7807 統一）

ProblemDetails:
  type: object
  properties:
    type:
      type: string
      format: uri
    title:
      type: string
    status:
      type: integer
    detail:
      type: string
    instance:
      type: string
      format: uri

Step 5: OpenAPI YAML生成

基本構造

openapi: 3.0.3
info:
  title: [APIタイトル]
  version: 1.0.0
  description: [API説明]
servers:
  - url: https://api.example.com/v1
    description: Production

paths セクション

エンドポイントごとに summary, operationId, tags, parameters, requestBody, responses, security を定義。

components セクション

• schemas: リクエスト/レスポンスのデータ定義
• securitySchemes: 認証方式の定義（bearerAuth, apiKey 等）
• responses: 共通エラーレスポンス（BadRequest, Unauthorized, NotFound）

ファイル出力

Step 6: バリデーション

npx @apidevtools/swagger-cli validate openapi.yaml

チェック項目:
- YAML構文エラーなし
- OpenAPI 3.x 仕様準拠
- $ref 参照が正しい
- 必須フィールドが存在

品質ゲート（Quality Checklist）

RESTful設計原則

• [ ] リソース名は複数形（/users, /products）
• [ ] URL に動詞を含まない
• [ ] kebab-case を使用
• [ ] ネストは最大2階層
• [ ] HTTPメソッドが適切

ステータスコード

• [ ] 成功時のステータスコードが適切（200, 201, 204）
• [ ] エラー時のステータスコードが適切（400, 401, 403, 404, 500）
• [ ] 201 Created 時に Location ヘッダーを返す

認証・認可

• [ ] 認証が必要なエンドポイントに security を定義
• [ ] securitySchemes を定義

ページネーション

• [ ] 一覧取得エンドポイントにページネーションパラメータ
• [ ] レスポンスにページネーション情報

エラーレスポンス

• [ ] 全エラーが統一フォーマット（RFC 7807 推奨）
• [ ] 400, 401, 403, 404, 500 のレスポンススキーマを定義

ドキュメント品質

• [ ] 各エンドポイントに summary と description
• [ ] タグでエンドポイントを分類

例

UC1: 新規API設計

入力: 「ブログAPIを設計して。記事の作成、取得、更新、削除ができるようにしたい。」

出力骨子:

openapi: 3.0.3
info:
  title: Blog API
  version: 1.0.0
paths:
  /posts:
    get:
      summary: 記事一覧取得
      responses:
        '200':
          description: 成功
    post:
      summary: 記事作成
      responses:
        '201':
          description: 作成成功
  /posts/{id}:
    get:
      summary: 記事詳細取得
    put:
      summary: 記事更新
    delete:
      summary: 記事削除
      responses:
        '204':
          description: 削除成功

UC2: 既存コードからAPI仕様書生成

入力: 「このExpressアプリのAPIドキュメントを作って」

処理: Expressのルート定義ファイルを検索 → ルート解析 → 型定義があれば抽出 → OpenAPI YAML生成

UC3: API設計レビュー

入力: 「このAPI設計をレビューして」（既存の openapi.yaml を提示）

出力例:
- RESTful命名規約違反の指摘と修正案
- ステータスコードの適切性チェック
- エラーレスポンス・ページネーションの不足指摘

参照

• OpenAPIパターン集
• RESTful設計原則

エラー処理