OpenAPI: REST API 注文CRUDエンドポイント

注文CRUD APIの定義

注文APIは単純なCRUDにはない概念を導入します：ネストされたリソース（明細項目）、ステータスのステートマシン、計算フィールド（合計）。

ネストされた項目を持つ注文スキーマ

components:
  schemas:
    Order:
      type: object
      required:
        - id
        - customerId
        - items
        - status
      properties:
        id:
          type: string
        customerId:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
        status:
          type: string
          enum:
            - pending
            - confirmed
            - shipped
            - delivered
            - cancelled
        totalAmount:
          type: number
        createdAt:
          type: string
    LineItem:
      type: object
      required:
        - productId
        - quantity
      properties:
        productId:
          type: string
        quantity:
          type: integer
        unitPrice:
          type: number

PATCHによるステータス遷移

注文の完全なPUT更新を許可する代わりに、PATCHを使用してステータスなどの特定フィールドを更新します：

/orders/{id}/status:
  patch:
    summary: Update order status
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - status
            properties:
              status:
                type: string
                enum:
                  - confirmed
                  - shipped
                  - delivered
                  - cancelled
    responses:
      '200':
        description: Status updated
      '400':
        description: Invalid status transition

設計上の考慮事項

• ステータスのenum: OpenAPIでenumを使用すると有効なステータス値を文書化でき、コードジェネレーターが型安全なステータス処理を作成できます。
• 計算フィールド: totalAmountは明細項目から計算され、読み取り専用であるべきです。OpenAPI 3.0ではreadOnly: trueでマークします。
• ネストされた作成: 注文作成時、items配列はリクエストボディで送信されます。サーバーが商品価格を解決し、合計を計算します。