api-designlisted

# API設計スキル OpenAPI/Swagger仕様書の作成とRESTful API設計を効率的に行うためのガイド。新規設計は「API設計ワークフロー」、既存仕様の変更は「既存OpenAPI仕様書の編集ワークフロー」、レビュー依頼は「レビューワークフロー」から始める。 ## API設計ワークフロー ### Step 1: 要件確認 以下を確認する: 1. APIの目的と対象ドメイン 2. 対象クライアント（Web、モバイル、外部サービスなど） 3. 認証・認可方式（OAuth2、API Key、JWTなど） 4. バージョニング戦略（URL、ヘッダー、クエリパラメータ） ### Step 2: リソース設計 リソース命名は「名詞・複数形・ケバブケース」（`/users`, `/user-profiles`）を基本とし、所属関係は `/users/{userId}/orders` のような階層で表現する。RESTで表現しにくいアクションの扱いを含む詳細は [references/best-practices.md](references/best-practices.md) の「リソース設計」を参照。 ### Step 3: OpenAPI仕様書作成 最小の骨組み（info / 1 endpoint / 1 schema）: ```yaml openapi: 3.1.0 info: title: User API version: 1.0.0 description: APIの説明 servers: - url: https://api.example.com/v1 description: Production paths: /users/{userId}: get: summary: ユーザー詳細取得 operationId: getUser parameters: - name: userId in: path required: true schema: type: string format: uuid responses: '200': description: 成功 content: application/json: schema: $ref: '#/components/schemas/User' '404': description: リソース未検出 components: schemas: User: type: object required: - id - email - createdAt properties: id: type: string format: uuid readOnly: true email: type: string format: email name: