OpenAPI: フィルター付き検索エンドポイント

OpenAPIでの検索エンドポイントの文書化

検索エンドポイントは全文クエリと構造化フィルターを組み合わせます。クライアントが利用可能なフィルター、演算子、ソートオプションを理解する必要があるため、パラメータの慎重な文書化が必要です。

検索エンドポイント定義

paths:
  /search:
    get:
      summary: Search items with filters
      tags:
        - Search
      operationId: searchItems
      parameters:
        - name: q
          in: query
          schema:
            type: string
          description: Full-text search query
        - name: category
          in: query
          schema:
            type: string
            enum:
              - electronics
              - clothing
              - books
              - home
          description: Filter by category
        - name: minPrice
          in: query
          schema:
            type: number
          description: Minimum price filter
        - name: maxPrice
          in: query
          schema:
            type: number
          description: Maximum price filter
        - name: sort
          in: query
          schema:
            type: string
            enum:
              - relevance
              - price_asc
              - price_desc
              - newest
              - oldest
          description: Sort order (default relevance)
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0

検索レスポンススキーマ

components:
  schemas:
    SearchResult:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchItem'
        total:
          type: integer
          description: Total matching results
        facets:
          type: object
          description: Aggregated filter counts

検索APIの設計のコツ

• ソートオプションのenum: すべての有効なソート値をリストして、クライアントが利用可能なオプションを把握できるようにします。
• 日付形式: format: dateまたはformat: date-timeを使用して期待される日付形式を指定します。
• ファセット: 集計カウント（各カテゴリの項目数）を含めて、フィルターUIを実現します。
• デフォルト値: limit、offset、sortのデフォルト値を文書化して、パラメータが省略された場合の動作をクライアントに知らせます。