Path and Query Parameters in OpenAPI

Parameters in OpenAPI

Parameters are inputs that modify how an endpoint behaves. OpenAPI 3.0 supports four parameter locations: path, query, header, and cookie. Each has specific rules for definition and usage.

Path Parameters

Path parameters are part of the URL and always required:

/users/{userId}/posts/{postId}:
  get:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: postId
        in: path
        required: true
        schema:
          type: integer

Path parameters must have required: true — they are always mandatory since they are embedded in the URL structure.

Query Parameters

Query parameters filter, sort, or modify the response:

/products:
  get:
    parameters:
      - name: category
        in: query
        schema:
          type: string
          enum: [electronics, clothing, books]
      - name: sort
        in: query
        schema:
          type: string
          enum: [price_asc, price_desc, newest]
          default: newest
      - name: min_price
        in: query
        schema:
          type: number
          minimum: 0
      - name: max_price
        in: query
        schema:
          type: number

Header Parameters

Custom request headers:

parameters:
  - name: X-Request-ID
    in: header
    required: false
    schema:
      type: string
      format: uuid
    description: Unique identifier for request tracing

Reusable Parameters

Define once, reference everywhere:

components:
  parameters:
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        minimum: 1
    PerPageParam:
      name: per_page
      in: query
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100

paths:
  /users:
    get:
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/PerPageParam"

Parameter Serialization

Control how array and object parameters are serialized:

- name: tags
  in: query
  schema:
    type: array
    items:
      type: string
  style: form
  explode: true   # ?tags=a&tags=b

• style: form, explode: true (default) produces ?tags=a&tags=b
• style: form, explode: false produces ?tags=a,b

Parameter Examples

Add examples for documentation clarity:

- name: date_from
  in: query
  schema:
    type: string
    format: date
  example: "2024-01-01"