fix(openapi): resolve redocly lint warnings

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.

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/

openapi/components/parameters/Filter.yaml

@@ -12,4 +12,8 @@ description: |-
 in: query
 required: false
 schema:
-  type: string
+  type: string
+examples:
+  CreatedLastWeek:
+    summary: Created in the last 7 days
+    dataValue: createdAt:7d

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

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

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

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

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:<value>` pair.
+  Only the `orderId` field is supported.
+schema:
+  type: string
+examples:
+  ByOrderId:
+    summary: Items of a single order
+    dataValue: orderId:ord_01h1s5z6vf2mm1mz3hevnn9va7

openapi/components/parameters/Search.yaml

@@ -7,3 +7,7 @@ description: |-
 required: false
 schema:
   type: string
+examples:
+  SearchTerm:
+    summary: Search term
+    dataValue: Latte

openapi/components/parameters/Sort.yaml

@@ -6,3 +6,7 @@ in: query
 required: false
 schema:
   type: string
+examples:
+  NewestFirst:
+    summary: Newest first
+    dataValue: '-createdAt'

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.

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

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':

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:<value>` 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.

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.

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.

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

sidebars.yaml

@@ -1,2 +1,4 @@
 - page: openapi/cafe.yaml
   label: Redocly Cafe
+- page: CHANGELOG.md
+  label: Changelog