API仕様書作成エージェント

役割

RESTful APIの仕様書をOpenAPI形式で作成します。

仕様書構成

docs/api/
├── openapi.yaml             # メインOpenAPI定義
├── schemas/                 # スキーマ定義
│   ├── user.yaml
│   ├── order.yaml
│   └── common.yaml
├── paths/                   # エンドポイント定義
│   ├── auth.yaml
│   ├── users.yaml
│   └── orders.yaml
└── examples/                # リクエスト/レスポンス例
    ├── user-examples.yaml
    └── order-examples.yaml

OpenAPI テンプレート

メイン定義 (openapi.yaml)

yaml
1openapi: 3.0.3
2info:
3  title: [プロジェクト名] API
4  description: |
5    [プロジェクトの説明]
6
7    ## 認証
8    Bearer Tokenによる認証を使用します。
9    `Authorization: Bearer <token>` ヘッダーを付与してください。
10
11  version: 1.0.0
12  contact:
13    name: API Support
14    email: support@example.com
15
16servers:
17  - url: https://api.example.com/v1
18    description: Production
19  - url: https://api.staging.example.com/v1
20    description: Staging
21  - url: http://localhost:8000/v1
22    description: Development
23
24tags:
25  - name: auth
26    description: 認証関連
27  - name: users
28    description: ユーザー管理
29  - name: orders
30    description: 注文管理
31
32security:
33  - bearerAuth: []
34
35paths:
36  $ref: './paths/_index.yaml'
37
38components:
39  securitySchemes:
40    bearerAuth:
41      type: http
42      scheme: bearer
43      bearerFormat: JWT
44
45  schemas:
46    $ref: './schemas/_index.yaml'
47
48  responses:
49    BadRequest:
50      description: Bad Request
51      content:
52        application/json:
53          schema:
54            $ref: '#/components/schemas/Error'
55    Unauthorized:
56      description: Unauthorized
57      content:
58        application/json:
59          schema:
60            $ref: '#/components/schemas/Error'
61    NotFound:
62      description: Not Found
63      content:
64        application/json:
65          schema:
66            $ref: '#/components/schemas/Error'

エンドポイント定義 (paths/users.yaml)

yaml
1/users:
2  get:
3    tags:
4      - users
5    summary: ユーザー一覧取得
6    description: 登録されているユーザーの一覧を取得します
7    operationId: getUsers
8    parameters:
9      - name: page
10        in: query
11        description: ページ番号
12        schema:
13          type: integer
14          default: 1
15          minimum: 1
16      - name: limit
17        in: query
18        description: 1ページあたりの件数
19        schema:
20          type: integer
21          default: 20
22          minimum: 1
23          maximum: 100
24      - name: status
25        in: query
26        description: ステータスでフィルタ
27        schema:
28          type: string
29          enum: [active, inactive, suspended]
30    responses:
31      '200':
32        description: 成功
33        content:
34          application/json:
35            schema:
36              type: object
37              properties:
38                data:
39                  type: array
40                  items:
41                    $ref: '../schemas/user.yaml#/User'
42                pagination:
43                  $ref: '../schemas/common.yaml#/Pagination'
44      '401':
45        $ref: '../openapi.yaml#/components/responses/Unauthorized'
46
47  post:
48    tags:
49      - users
50    summary: ユーザー作成
51    description: 新規ユーザーを作成します
52    operationId: createUser
53    security: []  # 認証不要
54    requestBody:
55      required: true
56      content:
57        application/json:
58          schema:
59            $ref: '../schemas/user.yaml#/CreateUserRequest'
60          example:
61            email: user@example.com
62            password: SecurePass123!
63            name: 山田太郎
64    responses:
65      '201':
66        description: 作成成功
67        content:
68          application/json:
69            schema:
70              $ref: '../schemas/user.yaml#/User'
71      '400':
72        $ref: '../openapi.yaml#/components/responses/BadRequest'
73      '409':
74        description: メールアドレス重複
75        content:
76          application/json:
77            schema:
78              $ref: '../schemas/common.yaml#/Error'
79
80/users/{userId}:
81  get:
82    tags:
83      - users
84    summary: ユーザー詳細取得
85    operationId: getUser
86    parameters:
87      - name: userId
88        in: path
89        required: true
90        description: ユーザーID
91        schema:
92          type: string
93          format: uuid
94    responses:
95      '200':
96        description: 成功
97        content:
98          application/json:
99            schema:
100              $ref: '../schemas/user.yaml#/User'
101      '404':
102        $ref: '../openapi.yaml#/components/responses/NotFound'
103
104  put:
105    tags:
106      - users
107    summary: ユーザー更新
108    operationId: updateUser
109    parameters:
110      - name: userId
111        in: path
112        required: true
113        schema:
114          type: string
115          format: uuid
116    requestBody:
117      required: true
118      content:
119        application/json:
120          schema:
121            $ref: '../schemas/user.yaml#/UpdateUserRequest'
122    responses:
123      '200':
124        description: 更新成功
125        content:
126          application/json:
127            schema:
128              $ref: '../schemas/user.yaml#/User'
129
130  delete:
131    tags:
132      - users
133    summary: ユーザー削除
134    operationId: deleteUser
135    parameters:
136      - name: userId
137        in: path
138        required: true
139        schema:
140          type: string
141          format: uuid
142    responses:
143      '204':
144        description: 削除成功

スキーマ定義 (schemas/user.yaml)

yaml
1User:
2  type: object
3  properties:
4    id:
5      type: string
6      format: uuid
7      description: ユーザーID
8      example: 550e8400-e29b-41d4-a716-446655440000
9    email:
10      type: string
11      format: email
12      description: メールアドレス
13      example: user@example.com
14    name:
15      type: string
16      description: 表示名
17      example: 山田太郎
18    status:
19      type: string
20      enum: [active, inactive, suspended]
21      description: ステータス
22      example: active
23    createdAt:
24      type: string
25      format: date-time
26      description: 作成日時
27    updatedAt:
28      type: string
29      format: date-time
30      description: 更新日時
31  required:
32    - id
33    - email
34    - name
35    - status
36    - createdAt
37    - updatedAt
38
39CreateUserRequest:
40  type: object
41  properties:
42    email:
43      type: string
44      format: email
45      description: メールアドレス
46      maxLength: 255
47    password:
48      type: string
49      format: password
50      description: パスワード（8文字以上、英数字記号混在）
51      minLength: 8
52      maxLength: 100
53    name:
54      type: string
55      description: 表示名
56      minLength: 1
57      maxLength: 100
58  required:
59    - email
60    - password
61    - name
62
63UpdateUserRequest:
64  type: object
65  properties:
66    name:
67      type: string
68      minLength: 1
69      maxLength: 100
70    status:
71      type: string
72      enum: [active, inactive]

共通スキーマ (schemas/common.yaml)

yaml
1Error:
2  type: object
3  properties:
4    error:
5      type: object
6      properties:
7        code:
8          type: string
9          description: エラーコード
10          example: "2001"
11        message:
12          type: string
13          description: エラーメッセージ
14          example: "Validation failed"
15        details:
16          type: array
17          items:
18            type: object
19            properties:
20              field:
21                type: string
22              message:
23                type: string
24        traceId:
25          type: string
26          description: トレースID
27          example: "abc123-def456"
28
29Pagination:
30  type: object
31  properties:
32    page:
33      type: integer
34      description: 現在のページ
35      example: 1
36    limit:
37      type: integer
38      description: 1ページあたりの件数
39      example: 20
40    totalItems:
41      type: integer
42      description: 総件数
43      example: 100
44    totalPages:
45      type: integer
46      description: 総ページ数
47      example: 5

API設計ガイドライン

URL設計

ステータスコード

ページネーション

GET /users?page=2&limit=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "totalItems": 100,
    "totalPages": 5
  }
}

コマンド

bash
1# OpenAPI仕様の検証
2npx @redocly/cli lint docs/api/openapi.yaml
3
4# ドキュメント生成
5npx @redocly/cli build-docs docs/api/openapi.yaml -o docs/api-docs.html
6
7# モックサーバー起動
8npx prism mock docs/api/openapi.yaml
9
10# クライアントコード生成
11npx openapi-generator-cli generate -i docs/api/openapi.yaml -g typescript-axios -o src/api

出力形式

API仕様書作成時の成果物：

1. OpenAPI定義: docs/api/openapi.yaml
2. スキーマ定義: docs/api/schemas/*.yaml
3. パス定義: docs/api/paths/*.yaml
4. HTMLドキュメント: docs/api-docs.html（生成）

関連スキル

• 基本設計書エージェント: API全体設計を参照
• 詳細設計書エージェント: 内部実装設計と連携
• 実装エージェント: API仕様に基づいて実装
• E2Eテストエージェント: APIテストを作成