api-designlisted

# API設計スキル OpenAPI/Swagger仕様書の作成とRESTful API設計を効率的に行うためのガイド。 ## ワークフロー判定 ### 新規API設計 → 「API設計ワークフロー」へ ### 既存OpenAPI仕様の編集 → 「仕様書編集ワークフロー」へ ### API設計レビュー → 「レビューワークフロー」へ --- ## API設計ワークフロー ### Step 1: 要件確認 以下を確認する: 1. APIの目的と対象ドメイン 2. 対象クライアント（Web、モバイル、外部サービスなど） 3. 認証・認可方式（OAuth2、API Key、JWTなど） 4. バージョニング戦略（URL、ヘッダー、クエリパラメータ） ### Step 2: リソース設計 RESTfulリソースの命名規則: - 名詞を使用（動詞は避ける） - 複数形を使用: `/users`, `/orders` - 階層関係を表現: `/users/{userId}/orders` - ケバブケースを使用: `/user-profiles` ### Step 3: OpenAPI仕様書作成 基本構造: ```yaml openapi: 3.1.0 info: title: API名 version: 1.0.0 description: APIの説明 servers: - url: https://api.example.com/v1 description: Production - url: https://api-staging.example.com/v1 description: Staging paths: /resources: get: # ... components: schemas: # ... securitySchemes: # ... ``` --- ## 既存OpenAPI仕様書の編集ワークフロー 1. 既存仕様の `openapi` バージョン、分割構成、共通 schema、security scheme、既存命名規則を確認する。 2. 変更対象の endpoint / schema / response を特定し、不要な再整形や無関係な並び替えを避ける。 3. 破壊的変更（パス削除、必須フィー���ド追加、型変更、レスポンス形式変更、認証スコープ変更）がある場合は、互換性への影響を明示してユーザー確認を取る。 4. 既存スタイルに合わせて最小差分で編集する。 5. `openapi validate`、`redocly lint`、`swagger-cli validate` など、プロジェクトで使われている検証コマンドを優先して実行する。無ければ実行できなかった理由を報告する。 6. 最終報告には変更した endpoint / schema、互換性影響、実行した検証、未検証リスクを含める。 ## RESTful設計原則 ### HTTPメソッドの使い分け | メソッド | 用途 | 冪等性 | 安全性 | |---------|------|--------|--------| | GET | リソース取得 | Yes | Yes | | POST | リソース作成 | No | No | | PUT | リソース全体更新 | Yes | No | | PATCH | リソース部分更新 | No