OpenAPI: REST API 商品CRUDエンドポイント

商品CRUD APIの定義

ECサイトの商品APIは、基本的なCRUDパターンをドメイン固有のフィールドとフィルタリング機能で拡張します。

商品スキーマ

components:
  schemas:
    Product:
      type: object
      required:
        - id
        - name
        - price
      properties:
        id:
          type: string
          description: Unique product identifier
        name:
          type: string
          description: Product display name
        price:
          type: number
          description: Price in USD
        category:
          type: string
          description: Product category
        inStock:
          type: boolean
          description: Whether the product is currently in stock
        imageUrl:
          type: string
          description: URL of the product image

フィルタリングパラメータ

商品APIは通常、カテゴリ、価格範囲、在庫状況によるフィルタリングをサポートします：

parameters:
  - name: category
    in: query
    schema:
      type: string
    description: Filter by category name
  - name: minPrice
    in: query
    schema:
      type: number
    description: Minimum price filter
  - name: maxPrice
    in: query
    schema:
      type: number
    description: Maximum price filter
  - name: inStock
    in: query
    schema:
      type: boolean
    description: Filter by stock availability

価格の扱い

価格にはtype: integerではなくtype: numberを使用します（小数値を含むため）。実際には、浮動小数点の問題を避けるために多くのAPIが最小通貨単位（セント）を整数として送信します。選択をフィールドの説明に記載してください。

画像アップロード

商品画像には、メインのCRUD操作に含めるのではなく、multipart/form-dataコンテンツタイプを持つ別のPOST /products/{id}/imagesエンドポイントを定義します。