OpenAPI: Search Endpoint with Filters

Q: OpenAPI: Search Endpoint with Filters

## Documenting a Search Endpoint in OpenAPI Search endpoints combine full-text queries with structured filters. They require careful parameter documentation because clients need to understand available filters, operators, and sort options. ### Search Endpoint Definition yaml paths: /search: get: summary: Search items with filters tags: - Search operationId: searchItems parameters: - name: q in: query schema: type: s

Document a search API endpoint with query parameters for full-text search, field filters, date ranges, sorting, and pagination in OpenAPI 3.0 format.

Search & Filtering

Detailed Explanation

Documenting a Search Endpoint in OpenAPI

Search endpoints combine full-text queries with structured filters. They require careful parameter documentation because clients need to understand available filters, operators, and sort options.

Search Endpoint Definition

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: dateFrom
          in: query
          schema:
            type: string
            format: date
          description: Filter items created after this date (YYYY-MM-DD)
        - name: dateTo
          in: query
          schema:
            type: string
            format: date
          description: Filter items created before this date
        - 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

Search Response Schema

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

Design Tips for Search APIs

Enum for sort options: List all valid sort values so clients know what is available.
Date formats: Use format: date or format: date-time to specify expected date formats.
Facets: Include aggregation counts (how many items in each category) to enable filter UIs.
Default values: Document defaults for limit, offset, and sort so clients know what to expect when parameters are omitted.

Use Case

Building a product catalog search, content management search, or any API where users need to filter, sort, and paginate through large datasets with multiple criteria.

Try It — API Documentation Generator

Open full tool →