Query Filtering and Sorting in OpenAPI

Q: Query Filtering and Sorting in OpenAPI

## Filtering and Sorting in OpenAPI List endpoints often need complex query parameters for filtering, sorting, and selecting fields. Documenting these clearly in OpenAPI helps consumers build correct requests and tools generate accurate client code. ### Simple Field Filtering yaml /products: get: parameters: - name: category in: query schema: type: string enum: [electronics, clothing, books, food] - name: brand in: query sc

Document filtering, sorting, and field selection query parameters in OpenAPI. Define complex query patterns for searchable list endpoints with enum constraints, range filters, and sort orders.

Endpoint Patterns

Detailed Explanation

Filtering and Sorting in OpenAPI

List endpoints often need complex query parameters for filtering, sorting, and selecting fields. Documenting these clearly in OpenAPI helps consumers build correct requests and tools generate accurate client code.

Simple Field Filtering

/products:
  get:
    parameters:
      - name: category
        in: query
        schema:
          type: string
          enum: [electronics, clothing, books, food]
      - name: brand
        in: query
        schema:
          type: string
      - name: in_stock
        in: query
        schema:
          type: boolean
          default: true

Range Filters

For numeric and date ranges:

parameters:
  - name: min_price
    in: query
    schema:
      type: number
      minimum: 0
  - name: max_price
    in: query
    schema:
      type: number
  - name: created_after
    in: query
    schema:
      type: string
      format: date-time
    example: "2024-01-01T00:00:00Z"
  - name: created_before
    in: query
    schema:
      type: string
      format: date-time

Sorting

- name: sort_by
  in: query
  schema:
    type: string
    enum: [name, price, created_at, rating]
    default: created_at
- name: sort_order
  in: query
  schema:
    type: string
    enum: [asc, desc]
    default: desc

Text Search

- name: q
  in: query
  schema:
    type: string
    minLength: 2
  description: Full-text search across name and description

Field Selection (Sparse Fieldsets)

- name: fields
  in: query
  schema:
    type: array
    items:
      type: string
      enum: [id, name, price, description, category]
  style: form
  explode: false
  description: Comma-separated list of fields to include
  example: "id,name,price"

Combined Example

A fully documented list endpoint:

/products:
  get:
    summary: Search and filter products
    tags: [products]
    parameters:
      - name: q
        in: query
        schema:
          type: string
      - name: category
        in: query
        schema:
          type: string
          enum: [electronics, clothing, books]
      - name: min_price
        in: query
        schema:
          type: number
      - name: max_price
        in: query
        schema:
          type: number
      - name: sort
        in: query
        schema:
          type: string
          enum: [price_asc, price_desc, newest, relevance]
          default: relevance
      - $ref: "#/components/parameters/PageParam"
      - $ref: "#/components/parameters/PerPageParam"

Organizing parameters with reusable $ref references keeps complex filtering endpoints readable and maintainable.

Use Case

Complex filtering and sorting documentation is essential for e-commerce APIs, search platforms, analytics dashboards, and any data-heavy application. Frontend developers building filter UIs need to know available filter fields, valid values, and sort options. Clear parameter documentation with enums and examples dramatically reduces integration time and API support requests.

Try It — OpenAPI Editor & Viewer

Open full tool →