docs: document per-endpoint filter, sort, and search fields

openapi/components/parameters/Filter.yaml

@@ -1,21 +1,15 @@
 name: filter
 description: |-
   Filters the collection items using space-separated `field:value` pairs.
+  See each list endpoint for the specific fields it supports.
 
   **Format:** `field1:value1 field2:value2`
 
   **Supported operators:**
   - `field:value` - exact match
   - `field:value1,value2` - match any of the comma-separated values (OR)
-  - Time ranges: use `30d` (30 days), `7d` (7 days), `1h` (1 hour), etc.
-
-  **Examples:**
-  - `status:placed` - filter by single status.
-  - `status:placed,completed` - filter by multiple statuses.
-  - `createdAt:30d` - filter orders created in the last 30 days.
-  - `orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7` - filter by specific order ID.
-  - `status:placed createdAt:7d` - combine multiple filters.
+  - Time ranges (on date fields): use `30d` (30 days), `7d` (7 days), `1h` (1 hour), etc.
 in: query
 required: false
 schema:
-  type: string
+  type: string

openapi/components/parameters/Search.yaml

@@ -1,13 +1,9 @@
 name: search
 in: query
 description: |-
-  Performs a case-insensitive text search across relevant fields in the collection.
-
-  **Fields searched depend on the endpoint:**
-  - **Menu items:** `name`, `photoTextDescription`
-  - **Orders:** `customerName`, `id`
-
-  Returns items where any of the searchable fields contain the search term as a substring.
+  Performs a case-insensitive text search across the endpoint's searchable fields,
+  returning items where any of those fields contain the search term as a substring.
+  See each list endpoint for the specific fields it searches.
 required: false
 schema:
   type: string

openapi/paths/menu.yaml

@@ -9,8 +9,39 @@ get:
     - $ref: ../components/parameters/After.yaml
     - $ref: ../components/parameters/Before.yaml
     - $ref: ../components/parameters/Sort.yaml
+      description: |-
+        Sorts the collection by a single field. Prefix with `-` for descending order
+        (for example, `-price`); omit the prefix for ascending order (`price`).
+
+        **Sortable fields:** `name`, `price`, `createdAt`, `updatedAt`, `id`
+      example: '-price'
     - $ref: ../components/parameters/Filter.yaml
+      description: |-
+        Filters the collection items using space-separated `field:value` pairs.
+
+        **Filterable fields:** `name`, `category`, `price`, `createdAt`, `id`
+
+        **Format:** `field1:value1 field2:value2`
+
+        **Supported operators:**
+        - `field:value` - Exact match
+        - `field:value1,value2` - Match any of the comma-separated values (OR)
+        - Time ranges (on `createdAt`): Use `30d` (30 days), `7d` (7 days), `1h` (1 hour), etc.
+
+        **Examples:**
+        - `category:beverage` - Filter by a single category.
+        - `category:beverage,dessert` - Filter by multiple categories.
+        - `createdAt:7d` - Menu items created in the last 7 days.
+        - `name:Latte` - Filter by name.
+        - `category:beverage price:400` - Combine multiple filters.
+      example: category:beverage
     - $ref: ../components/parameters/Search.yaml
+      description: |-
+        Performs a case-insensitive text search across the searchable fields, returning
+        items where any of them contain the search term as a substring.
+
+        **Searchable fields:** `name`, `photoTextDescription`
+      example: Latte
     - $ref: ../components/parameters/Limit.yaml
   responses:
     '200':

openapi/paths/order-items.yaml

@@ -12,6 +12,12 @@ get:
   parameters:
     - $ref: ../components/parameters/Filter.yaml
       required: true
+      description: |-
+        Selects the order whose items to return, using a single `orderId:<value>` pair
+        (for example, `orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7`).
+
+        This filter is required and only the `orderId` field is supported.
+      example: orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7
   responses:
     '200':
       description: Successful operation.

openapi/paths/orders.yaml

@@ -9,11 +9,42 @@ get:
         - orders:read
   parameters:
     - $ref: ../components/parameters/Filter.yaml
+      description: |-
+        Filters the collection items using space-separated `field:value` pairs.
+
+        **Filterable fields:** `customerName`, `status`, `totalPrice`, `createdAt`, `id`
+
+        **Format:** `field1:value1 field2:value2`
+
+        **Supported operators:**
+        - `field:value` - Exact match
+        - `field:value1,value2` - Match any of the comma-separated values (OR)
+        - Time ranges (on `createdAt`): Use `30d` (30 days), `7d` (7 days), `1h` (1 hour), etc.
+
+        **Examples:**
+        - `status:placed` - Filter by a single status.
+        - `status:placed,completed` - Filter by multiple statuses.
+        - `createdAt:30d` - Orders created in the last 30 days.
+        - `id:ord_01h1s5z6vf2mm1mz3hevnn9va7` - Filter by a specific order ID.
+        - `status:placed createdAt:7d` - Combine multiple filters.
+      example: status:placed
     - $ref: ../components/parameters/Sort.yaml
+      description: |-
+        Sorts the collection by a single field. Prefix with `-` for descending order
+        (for example, `-createdAt`); omit the prefix for ascending order (`createdAt`).
+
+        **Sortable fields:** `customerName`, `status`, `totalPrice`, `createdAt`, `updatedAt`, `id`
+      example: '-createdAt'
     - $ref: ../components/parameters/Limit.yaml
     - $ref: ../components/parameters/After.yaml
     - $ref: ../components/parameters/Before.yaml
     - $ref: ../components/parameters/Search.yaml
+      description: |-
+        Performs a case-insensitive text search across the searchable fields, returning
+        items where any of them contain the search term as a substring.
+
+        **Searchable fields:** `customerName`, `id`
+      example: John
   responses:
     '200':
       description: Successful operation.