OpenAPI: REST API ユーザーCRUDエンドポイント

OpenAPIでの完全なCRUDユーザーAPI構築

CRUD APIは最も一般的なRESTパターンです。/usersリソースでは、コレクション（/users）と個別リソース（/users/{id}）の2つのパスパターンに5つの操作を定義します。

パス定義

paths:
  /users:
    get:
      summary: List all users
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create a user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: User created
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User found
        '404':
          description: User not found

主要な設計判断

• コレクションとリソースのパス: /usersは一覧と作成用、/users/{id}は個別ユーザーの読取、更新、削除用。
• OperationId: 各操作には一意のID（listUsers、createUser、getUserById、updateUser、deleteUser）を付けます。生成されたSDKでは関数名になります。
• スキーマ参照: $refを使用して再利用可能なスキーマを参照します。レスポンス用のUserスキーマと、リクエストボディ用のUserInputスキーマ（idやcreatedAtなどの自動生成フィールドを省略可能）を用意します。
• ステータスコード: 読取は200、作成は201、削除は204、バリデーションエラーは400、リソースが見つからない場合は404を返します。

レスポンススキーマ

id（string）、name（string）、email（string）、createdAt（string、format: date-time）のプロパティを持つUserコンポーネントを定義します。id、name、emailを必須としてマークします。