diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..01e30f3 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,15 @@ +# Changelog + +## 1.0.1 (2026-10-14) + +### Changed + +- Documented the `404` response of `GET /.well-known/oauth-authorization-server`. + +### Fixed + +- Fixed the `spec-ref-siblings` warnings reported by Redocly CLI. + +## 1.0.0 (2026-06-17) + +Initial public release. diff --git a/openapi/cafe.yaml b/openapi/cafe.yaml index 7f982c6..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.0.0 + version: 1.0.1 contact: email: team@redocly.com url: https://redocly.com/contact-us/ 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/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/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/order-items.yaml b/openapi/paths/order-items.yaml index adeab36..d5b7de8 100644 --- a/openapi/paths/order-items.yaml +++ b/openapi/paths/order-items.yaml @@ -10,14 +10,7 @@ get: - 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/OrderItemsFilter.yaml responses: '200': description: Successful operation. 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/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 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