From 932060b969c2ef9a274fe5383ddf4981b09e17db Mon Sep 17 00:00:00 2001 From: Vadym Vasylyshyn <51933329+vadyvas@users.noreply.github.com> Date: Fri, 9 Oct 2026 14:35:48 +0300 Subject: [PATCH 1/5] fix(openapi): resolve redocly lint warnings and nest order items under orders MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Redocly CLI 2.60 validates Reference Objects per OAS 3.2: only `summary` and `description` may sit next to `$ref`. Remove the `example` and `required` siblings, keep the description overrides, and move examples into the parameter components as `examples` + `dataValue`. - replace `GET /order-items` (required `filter=orderId:…`) with `GET /orders/{orderId}/items`, reusing the `OrderId` parameter - add `examples` to every parameter, including a new one for `menuItemId` - add a `404` response to the RFC 8414 metadata endpoint (operation-4xx-response) - flatten single-branch `allOf` in `Order.status` and `OrderItem.menuItem` to `$ref` with sibling keywords (JSON Schema 2020-12) Note: the live server does not serve `/orders/{orderId}/items` yet. --- openapi/cafe.yaml | 4 ++-- openapi/components/parameters/Filter.yaml | 6 +++++- openapi/components/parameters/Limit.yaml | 5 ++++- openapi/components/parameters/MenuItemId.yaml | 4 ++++ openapi/components/parameters/OAuth2ClientId.yaml | 5 ++++- openapi/components/parameters/OrderId.yaml | 5 ++++- openapi/components/parameters/Search.yaml | 4 ++++ openapi/components/parameters/Sort.yaml | 4 ++++ openapi/components/schemas/Order.yaml | 3 +-- openapi/components/schemas/OrderItem.yaml | 5 ++--- openapi/paths/menu.yaml | 3 --- openapi/paths/orders.yaml | 3 --- .../{order-items.yaml => orders_{orderId}_items.yaml} | 10 +--------- openapi/paths/revenue.yaml | 10 ++++++++-- .../paths/well-known_oauth-authorization-server.yaml | 3 +++ 15 files changed, 46 insertions(+), 28 deletions(-) rename openapi/paths/{order-items.yaml => orders_{orderId}_items.yaml} (66%) diff --git a/openapi/cafe.yaml b/openapi/cafe.yaml index 7f982c6..bd3be3a 100644 --- a/openapi/cafe.yaml +++ b/openapi/cafe.yaml @@ -35,8 +35,8 @@ paths: $ref: paths/orders.yaml /orders/{orderId}: $ref: paths/orders_{orderId}.yaml - /order-items: - $ref: paths/order-items.yaml + /orders/{orderId}/items: + $ref: paths/orders_{orderId}_items.yaml /revenue: $ref: paths/revenue.yaml /oauth2/register: diff --git a/openapi/components/parameters/Filter.yaml b/openapi/components/parameters/Filter.yaml index 16c5f12..3acd1b5 100644 --- a/openapi/components/parameters/Filter.yaml +++ b/openapi/components/parameters/Filter.yaml @@ -12,4 +12,8 @@ description: |- in: query required: false schema: - type: string \ No newline at end of file + type: string +examples: + CreatedLastWeek: + summary: Created in the last 7 days + dataValue: createdAt:7d diff --git a/openapi/components/parameters/Limit.yaml b/openapi/components/parameters/Limit.yaml index b960de0..26c65f0 100644 --- a/openapi/components/parameters/Limit.yaml +++ b/openapi/components/parameters/Limit.yaml @@ -9,4 +9,7 @@ schema: minimum: 1 maximum: 100 default: 10 -example: 10 +examples: + DefaultPageSize: + summary: Default page size + dataValue: 10 diff --git a/openapi/components/parameters/MenuItemId.yaml b/openapi/components/parameters/MenuItemId.yaml index 17b432d..191b3cc 100644 --- a/openapi/components/parameters/MenuItemId.yaml +++ b/openapi/components/parameters/MenuItemId.yaml @@ -5,3 +5,7 @@ required: true schema: type: string pattern: ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$ +examples: + MenuItemId: + summary: Menu item ID + dataValue: prd_01khr487f7qm7p44xn427m43vb diff --git a/openapi/components/parameters/OAuth2ClientId.yaml b/openapi/components/parameters/OAuth2ClientId.yaml index 866a5a3..0fc7139 100644 --- a/openapi/components/parameters/OAuth2ClientId.yaml +++ b/openapi/components/parameters/OAuth2ClientId.yaml @@ -4,4 +4,7 @@ required: true description: The client identifier issued at registration. schema: type: string -example: client_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d +examples: + ClientId: + summary: Client ID + dataValue: client_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d diff --git a/openapi/components/parameters/OrderId.yaml b/openapi/components/parameters/OrderId.yaml index 6431836..4e45878 100644 --- a/openapi/components/parameters/OrderId.yaml +++ b/openapi/components/parameters/OrderId.yaml @@ -5,4 +5,7 @@ required: true schema: type: string pattern: ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$ -example: ord_01h1s5z6vf2mm1mz3hevnn9va7 +examples: + OrderId: + summary: Order ID + dataValue: ord_01h1s5z6vf2mm1mz3hevnn9va7 diff --git a/openapi/components/parameters/Search.yaml b/openapi/components/parameters/Search.yaml index 7187781..520487d 100644 --- a/openapi/components/parameters/Search.yaml +++ b/openapi/components/parameters/Search.yaml @@ -7,3 +7,7 @@ description: |- required: false schema: type: string +examples: + SearchTerm: + summary: Search term + dataValue: Latte diff --git a/openapi/components/parameters/Sort.yaml b/openapi/components/parameters/Sort.yaml index cfe82a3..a8e9608 100644 --- a/openapi/components/parameters/Sort.yaml +++ b/openapi/components/parameters/Sort.yaml @@ -6,3 +6,7 @@ in: query required: false schema: type: string +examples: + NewestFirst: + summary: Newest first + dataValue: '-createdAt' diff --git a/openapi/components/schemas/Order.yaml b/openapi/components/schemas/Order.yaml index 5927f1c..538776e 100644 --- a/openapi/components/schemas/Order.yaml +++ b/openapi/components/schemas/Order.yaml @@ -22,8 +22,7 @@ properties: minLength: 1 maxLength: 100 status: - allOf: - - $ref: ./OrderStatus.yaml + $ref: ./OrderStatus.yaml readOnly: true totalPrice: description: Total order price in cents. diff --git a/openapi/components/schemas/OrderItem.yaml b/openapi/components/schemas/OrderItem.yaml index 44f778f..ae2989e 100644 --- a/openapi/components/schemas/OrderItem.yaml +++ b/openapi/components/schemas/OrderItem.yaml @@ -5,10 +5,9 @@ properties: description: ID of the menu item to add to the order. writeOnly: true menuItem: - allOf: - - $ref: ./MenuItem.yaml - description: Menu item that is part of the order. + $ref: ./MenuItem.yaml readOnly: true + description: Menu item that is part of the order. quantity: type: integer minimum: 1 diff --git a/openapi/paths/menu.yaml b/openapi/paths/menu.yaml index 6e59b25..73f4dba 100644 --- a/openapi/paths/menu.yaml +++ b/openapi/paths/menu.yaml @@ -14,7 +14,6 @@ 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. @@ -34,14 +33,12 @@ get: - `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': diff --git a/openapi/paths/orders.yaml b/openapi/paths/orders.yaml index f8c5e52..ed57ffe 100644 --- a/openapi/paths/orders.yaml +++ b/openapi/paths/orders.yaml @@ -27,14 +27,12 @@ get: - `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 @@ -44,7 +42,6 @@ get: items where any of them contain the search term as a substring. **Searchable fields:** `customerName`, `id` - example: John responses: '200': description: Successful operation. diff --git a/openapi/paths/order-items.yaml b/openapi/paths/orders_{orderId}_items.yaml similarity index 66% rename from openapi/paths/order-items.yaml rename to openapi/paths/orders_{orderId}_items.yaml index adeab36..cc9f598 100644 --- a/openapi/paths/order-items.yaml +++ b/openapi/paths/orders_{orderId}_items.yaml @@ -4,20 +4,12 @@ get: summary: List all order items with menu item details description: | Returns an array of order items for a specific order. - Use the `filter` parameter to filter by order ID. operationId: listOrderItems security: - OAuth2: - orders:read 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 + - $ref: ../components/parameters/OrderId.yaml responses: '200': description: Successful operation. diff --git a/openapi/paths/revenue.yaml b/openapi/paths/revenue.yaml index f90e261..b5bc42e 100644 --- a/openapi/paths/revenue.yaml +++ b/openapi/paths/revenue.yaml @@ -20,7 +20,10 @@ get: schema: type: string format: date-time - example: '2026-01-01T00:00:00Z' + examples: + StartOfJanuary: + summary: Start of January 2026 + dataValue: '2026-01-01T00:00:00Z' - name: endDate in: query required: false @@ -30,7 +33,10 @@ get: schema: type: string format: date-time - example: '2026-01-31T23:59:59Z' + examples: + EndOfJanuary: + summary: End of January 2026 + dataValue: '2026-01-31T23:59:59Z' responses: '200': description: Revenue statistics retrieved successfully. diff --git a/openapi/paths/well-known_oauth-authorization-server.yaml b/openapi/paths/well-known_oauth-authorization-server.yaml index 28412d3..34b3d88 100644 --- a/openapi/paths/well-known_oauth-authorization-server.yaml +++ b/openapi/paths/well-known_oauth-authorization-server.yaml @@ -48,5 +48,8 @@ get: - plain authorization_response_iss_parameter_supported: true service_documentation: https://cafe.redocly.com/openapi/cafe + '404': + $ref: ../components/responses/NotFound.yaml + description: Authorization server metadata is not available for this issuer (RFC 8414 Section 3). '500': $ref: ../components/responses/OAuth2ServerError.yaml From 8783d5d8a908023211cb58b87b3290adc8a08e1e Mon Sep 17 00:00:00 2001 From: Vadym Vasylyshyn <51933329+vadyvas@users.noreply.github.com> Date: Wed, 14 Oct 2026 16:18:40 +0300 Subject: [PATCH 2/5] docs: add changelog and bump API version to 1.1.0 --- CHANGELOG.md | 18 ++++++++++++++++++ openapi/cafe.yaml | 2 +- sidebars.yaml | 2 ++ 3 files changed, 21 insertions(+), 1 deletion(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..66f77b3 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,18 @@ +# Changelog + +## 1.1.0 (2026-10-14) + +### Changed + +- Replaced `GET /order-items?filter=orderId:` with `GET /orders/{orderId}/items`. + This is a breaking change: the old path returns `404`, and so does an unknown order instead of an empty list. +- Documented the `404` response of `GET /.well-known/oauth-authorization-server`. + +### Fixed + +- Fixed the `spec-ref-siblings` warnings reported by Redocly CLI 2.60 by moving parameter examples + into the shared parameter components as OAS 3.2 `examples`. + +## 1.0.0 (2026-06-17) + +Initial public release. diff --git a/openapi/cafe.yaml b/openapi/cafe.yaml index bd3be3a..8e70bdc 100644 --- a/openapi/cafe.yaml +++ b/openapi/cafe.yaml @@ -4,7 +4,7 @@ info: description: | Demo API for cafe operators (not customers) to manage menus, orders, and revenue. Create API credentials and try it yourself in a realistic OpenAPI workflow. - version: 1.0.0 + version: 1.1.0 contact: email: team@redocly.com url: https://redocly.com/contact-us/ diff --git a/sidebars.yaml b/sidebars.yaml index 9676783..9f971ab 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -1,2 +1,4 @@ - page: openapi/cafe.yaml label: Redocly Cafe +- page: CHANGELOG.md + label: Changelog From 80859b221e3a63e7c25defd5915588db96c699a7 Mon Sep 17 00:00:00 2001 From: Vadym Vasylyshyn <51933329+vadyvas@users.noreply.github.com> Date: Wed, 14 Oct 2026 16:29:26 +0300 Subject: [PATCH 3/5] chore: update changelog --- CHANGELOG.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 66f77b3..6970488 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,8 +10,7 @@ ### Fixed -- Fixed the `spec-ref-siblings` warnings reported by Redocly CLI 2.60 by moving parameter examples - into the shared parameter components as OAS 3.2 `examples`. +- Fixed the `spec-ref-siblings` warnings reported by Redocly CLI. ## 1.0.0 (2026-06-17) From 83ce9fa8ec819128babf792805b121dde79ac65e Mon Sep 17 00:00:00 2001 From: Vadym Vasylyshyn <51933329+vadyvas@users.noreply.github.com> Date: Wed, 14 Oct 2026 17:34:26 +0300 Subject: [PATCH 4/5] fix(openapi): keep /order-items top-level with a dedicated required filter --- CHANGELOG.md | 2 -- openapi/cafe.yaml | 4 ++-- openapi/components/parameters/OrderItemsFilter.yaml | 12 ++++++++++++ ...{orders_{orderId}_items.yaml => order-items.yaml} | 3 ++- 4 files changed, 16 insertions(+), 5 deletions(-) create mode 100644 openapi/components/parameters/OrderItemsFilter.yaml rename openapi/paths/{orders_{orderId}_items.yaml => order-items.yaml} (88%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6970488..e1eab0d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,8 +4,6 @@ ### Changed -- Replaced `GET /order-items?filter=orderId:` with `GET /orders/{orderId}/items`. - This is a breaking change: the old path returns `404`, and so does an unknown order instead of an empty list. - Documented the `404` response of `GET /.well-known/oauth-authorization-server`. ### Fixed diff --git a/openapi/cafe.yaml b/openapi/cafe.yaml index 8e70bdc..f026c35 100644 --- a/openapi/cafe.yaml +++ b/openapi/cafe.yaml @@ -35,8 +35,8 @@ paths: $ref: paths/orders.yaml /orders/{orderId}: $ref: paths/orders_{orderId}.yaml - /orders/{orderId}/items: - $ref: paths/orders_{orderId}_items.yaml + /order-items: + $ref: paths/order-items.yaml /revenue: $ref: paths/revenue.yaml /oauth2/register: diff --git a/openapi/components/parameters/OrderItemsFilter.yaml b/openapi/components/parameters/OrderItemsFilter.yaml new file mode 100644 index 0000000..05809b6 --- /dev/null +++ b/openapi/components/parameters/OrderItemsFilter.yaml @@ -0,0 +1,12 @@ +name: filter +in: query +required: true +description: |- + Selects the order whose items to return, using a single `orderId:` pair. + Only the `orderId` field is supported. +schema: + type: string +examples: + ByOrderId: + summary: Items of a single order + dataValue: orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7 diff --git a/openapi/paths/orders_{orderId}_items.yaml b/openapi/paths/order-items.yaml similarity index 88% rename from openapi/paths/orders_{orderId}_items.yaml rename to openapi/paths/order-items.yaml index cc9f598..d5b7de8 100644 --- a/openapi/paths/orders_{orderId}_items.yaml +++ b/openapi/paths/order-items.yaml @@ -4,12 +4,13 @@ get: summary: List all order items with menu item details description: | Returns an array of order items for a specific order. + Use the `filter` parameter to filter by order ID. operationId: listOrderItems security: - OAuth2: - orders:read parameters: - - $ref: ../components/parameters/OrderId.yaml + - $ref: ../components/parameters/OrderItemsFilter.yaml responses: '200': description: Successful operation. From 0e93eaf148dca804e97cb9b0f4f08b1ce17e53f4 Mon Sep 17 00:00:00 2001 From: Vadym Vasylyshyn <51933329+vadyvas@users.noreply.github.com> Date: Wed, 14 Oct 2026 17:47:32 +0300 Subject: [PATCH 5/5] chore: set API version to 1.0.1 The release only fixes lint warnings and documents existing behavior, so it is a patch, not a minor bump. Co-Authored-By: Claude Fable 5.1 --- CHANGELOG.md | 2 +- openapi/cafe.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e1eab0d..01e30f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## 1.1.0 (2026-10-14) +## 1.0.1 (2026-10-14) ### Changed diff --git a/openapi/cafe.yaml b/openapi/cafe.yaml index f026c35..6685235 100644 --- a/openapi/cafe.yaml +++ b/openapi/cafe.yaml @@ -4,7 +4,7 @@ info: description: | Demo API for cafe operators (not customers) to manage menus, orders, and revenue. Create API credentials and try it yourself in a realistic OpenAPI workflow. - version: 1.1.0 + version: 1.0.1 contact: email: team@redocly.com url: https://redocly.com/contact-us/