From 065fafd08a17915b537323c2523af834afae3893 Mon Sep 17 00:00:00 2001 From: rudi23 Date: Thu, 16 Jul 2026 15:49:24 +0200 Subject: [PATCH 1/3] docs: document per-endpoint filter, sort, and search fields Port the OpenAPI documentation changes from Redocly/redocly#25078 to the standalone cafe-api repo. - Generalize the shared Filter and Search parameter descriptions, pointing readers to each list endpoint for the specific fields it supports. - Add per-endpoint description overrides (and examples) documenting the filterable, sortable, and searchable fields for menu and orders. - Document that order-items filtering is required and orderId-only. Co-Authored-By: Claude Opus 4.8 --- openapi/components/parameters/Filter.yaml | 10 ++------ openapi/components/parameters/Search.yaml | 10 +++----- openapi/paths/menu.yaml | 29 +++++++++++++++++++++ openapi/paths/order-items.yaml | 6 +++++ openapi/paths/orders.yaml | 31 +++++++++++++++++++++++ 5 files changed, 71 insertions(+), 15 deletions(-) diff --git a/openapi/components/parameters/Filter.yaml b/openapi/components/parameters/Filter.yaml index 1e6f24d..9aa0e76 100644 --- a/openapi/components/parameters/Filter.yaml +++ b/openapi/components/parameters/Filter.yaml @@ -1,20 +1,14 @@ 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: diff --git a/openapi/components/parameters/Search.yaml b/openapi/components/parameters/Search.yaml index bc371ac..7187781 100644 --- a/openapi/components/parameters/Search.yaml +++ b/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 diff --git a/openapi/paths/menu.yaml b/openapi/paths/menu.yaml index 702ba50..dbda7bc 100644 --- a/openapi/paths/menu.yaml +++ b/openapi/paths/menu.yaml @@ -9,8 +9,37 @@ 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` - $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` - $ref: ../components/parameters/Limit.yaml responses: '200': diff --git a/openapi/paths/order-items.yaml b/openapi/paths/order-items.yaml index bbdd9ce..adeab36 100644 --- a/openapi/paths/order-items.yaml +++ b/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:` 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. diff --git a/openapi/paths/orders.yaml b/openapi/paths/orders.yaml index 7b816e4..f8c5e52 100644 --- a/openapi/paths/orders.yaml +++ b/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. From 6f4d9f5281d85eafb45476c388eaef7ffd55514e Mon Sep 17 00:00:00 2001 From: rudi23 Date: Thu, 16 Jul 2026 17:46:10 +0200 Subject: [PATCH 2/3] docs: constrain filter/search length and add menu examples Address AI review feedback on #18: - Add maxLength to the shared filter (512) and search (256) query parameters to bound query-string size. - Add example values to the menu sort and search parameters for consistency with the orders endpoint. Co-Authored-By: Claude Opus 4.8 --- openapi/components/parameters/Filter.yaml | 1 + openapi/components/parameters/Search.yaml | 1 + openapi/paths/menu.yaml | 2 ++ 3 files changed, 4 insertions(+) diff --git a/openapi/components/parameters/Filter.yaml b/openapi/components/parameters/Filter.yaml index 9aa0e76..8726000 100644 --- a/openapi/components/parameters/Filter.yaml +++ b/openapi/components/parameters/Filter.yaml @@ -13,3 +13,4 @@ in: query required: false schema: type: string + maxLength: 512 diff --git a/openapi/components/parameters/Search.yaml b/openapi/components/parameters/Search.yaml index 7187781..217cf5d 100644 --- a/openapi/components/parameters/Search.yaml +++ b/openapi/components/parameters/Search.yaml @@ -7,3 +7,4 @@ description: |- required: false schema: type: string + maxLength: 256 diff --git a/openapi/paths/menu.yaml b/openapi/paths/menu.yaml index dbda7bc..6e59b25 100644 --- a/openapi/paths/menu.yaml +++ b/openapi/paths/menu.yaml @@ -14,6 +14,7 @@ get: (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. @@ -40,6 +41,7 @@ get: 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': From d1b85103618584b01a357a4f2a402c71e14a4c75 Mon Sep 17 00:00:00 2001 From: rudi23 Date: Fri, 17 Jul 2026 16:55:51 +0200 Subject: [PATCH 3/3] fix: remove maxLength --- openapi/components/parameters/Filter.yaml | 3 +-- openapi/components/parameters/Search.yaml | 1 - 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/openapi/components/parameters/Filter.yaml b/openapi/components/parameters/Filter.yaml index 8726000..16c5f12 100644 --- a/openapi/components/parameters/Filter.yaml +++ b/openapi/components/parameters/Filter.yaml @@ -12,5 +12,4 @@ description: |- in: query required: false schema: - type: string - maxLength: 512 + type: string \ No newline at end of file diff --git a/openapi/components/parameters/Search.yaml b/openapi/components/parameters/Search.yaml index 217cf5d..7187781 100644 --- a/openapi/components/parameters/Search.yaml +++ b/openapi/components/parameters/Search.yaml @@ -7,4 +7,3 @@ description: |- required: false schema: type: string - maxLength: 256