From 804a2993c722a18793268ed9e6b8fbc3defe5d0a Mon Sep 17 00:00:00 2001
From: Vadym Vasylyshyn <51933329+vadyvas@users.noreply.github.com>
Date: Wed, 14 Oct 2026 17:50:36 +0300
Subject: [PATCH 1/7] feat(openapi): make the description pass the reunite
 starter rules

---
 openapi/components/responses/BadRequest.yaml  | 16 +++++++++++++
 openapi/components/responses/Conflict.yaml    |  8 +++++++
 openapi/components/responses/Forbidden.yaml   |  8 +++++++
 .../responses/InternalServerError.yaml        |  8 +++++++
 .../responses/MenuItemNotFound.yaml           | 13 +++++++++++
 openapi/components/responses/NotFound.yaml    |  8 +++++++
 .../responses/OAuth2BadRequest.yaml           |  6 +++++
 .../OAuth2RegistrationBadRequest.yaml         | 11 +++++++++
 .../OAuth2RegistrationUnauthorized.yaml       | 16 +++++++++++++
 .../responses/OAuth2ServerError.yaml          |  6 +++++
 .../responses/OAuth2Unauthorized.yaml         | 12 +++++++---
 .../components/responses/OrderNotFound.yaml   | 13 +++++++++++
 .../components/responses/Unauthorized.yaml    |  8 +++++++
 .../schemas/AuthorizationServerMetadata.yaml  | 14 +++++++++++
 openapi/components/schemas/Beverage.yaml      |  6 +++++
 openapi/components/schemas/Dessert.yaml       |  4 ++++
 openapi/components/schemas/Error.yaml         |  9 +++++++-
 openapi/components/schemas/MenuBaseItem.yaml  | 17 +++++++++++++-
 openapi/components/schemas/MenuItemList.yaml  |  2 ++
 openapi/components/schemas/OAuth2Client.yaml  | 23 +++++++++++++++++++
 openapi/components/schemas/OAuthError.yaml    |  4 ++++
 openapi/components/schemas/Order.yaml         | 21 ++++++++++++++++-
 openapi/components/schemas/OrderItem.yaml     |  8 +++++++
 openapi/components/schemas/OrderList.yaml     |  2 ++
 .../components/schemas/OrderNotification.yaml |  4 ++++
 openapi/components/schemas/OrderStatus.yaml   |  2 ++
 openapi/components/schemas/Page.yaml          |  2 ++
 .../schemas/RegisterClientMetadata.yaml       |  7 +++++-
 .../components/schemas/RevenueStatistics.yaml | 18 +++++++++++++++
 openapi/components/schemas/TokenResponse.yaml | 12 ++++++++--
 .../schemas/UpdateClientObject.yaml           |  4 ++++
 .../paths/menu-item-images_{menuItemId}.yaml  |  2 +-
 openapi/paths/menu_{menuItemId}.yaml          |  2 +-
 openapi/paths/oauth2_register.yaml            |  2 +-
 openapi/paths/oauth2_register_{clientId}.yaml |  8 +++----
 openapi/paths/oauth2_revoke.yaml              |  8 +++++++
 openapi/paths/oauth2_token.yaml               | 16 +++++++++++++
 openapi/paths/order-items.yaml                |  2 +-
 openapi/paths/orders_{orderId}.yaml           |  6 ++---
 redocly.yaml                                  | 19 +++++++++++++++
 40 files changed, 337 insertions(+), 20 deletions(-)
 create mode 100644 openapi/components/responses/MenuItemNotFound.yaml
 create mode 100644 openapi/components/responses/OAuth2RegistrationBadRequest.yaml
 create mode 100644 openapi/components/responses/OAuth2RegistrationUnauthorized.yaml
 create mode 100644 openapi/components/responses/OrderNotFound.yaml

diff --git a/openapi/components/responses/BadRequest.yaml b/openapi/components/responses/BadRequest.yaml
index 69820e0..8dcd599 100644
--- a/openapi/components/responses/BadRequest.yaml
+++ b/openapi/components/responses/BadRequest.yaml
@@ -3,3 +3,19 @@ content:
   application/problem+json:
     schema:
       $ref: ../schemas/Error.yaml
+    examples:
+      ValidationFailed:
+        summary: Request body failed validation
+        dataValue:
+          type: about:blank
+          title: Validation failed
+          status: 400
+          instance: /orders
+          details:
+            errors:
+              - code: invalid_type
+                expected: string
+                received: undefined
+                path:
+                  - customerName
+                message: Required
diff --git a/openapi/components/responses/Conflict.yaml b/openapi/components/responses/Conflict.yaml
index 5a4a8f9..b3e9f32 100644
--- a/openapi/components/responses/Conflict.yaml
+++ b/openapi/components/responses/Conflict.yaml
@@ -3,3 +3,11 @@ content:
   application/problem+json:
     schema:
       $ref: ../schemas/Error.yaml
+    examples:
+      DuplicateName:
+        summary: Menu item name is already taken
+        dataValue:
+          type: about:blank
+          title: A menu item with the name "coffee" already exists
+          status: 409
+          instance: /menu
diff --git a/openapi/components/responses/Forbidden.yaml b/openapi/components/responses/Forbidden.yaml
index 6166b76..1d74551 100644
--- a/openapi/components/responses/Forbidden.yaml
+++ b/openapi/components/responses/Forbidden.yaml
@@ -3,3 +3,11 @@ content:
   application/problem+json:
     schema:
       $ref: ../schemas/Error.yaml
+    examples:
+      InsufficientScopes:
+        summary: Access token lacks the required scope
+        dataValue:
+          type: about:blank
+          title: 'Insufficient scopes. Required: orders:read'
+          status: 403
+          instance: /orders
diff --git a/openapi/components/responses/InternalServerError.yaml b/openapi/components/responses/InternalServerError.yaml
index 07bd4ea..3677788 100644
--- a/openapi/components/responses/InternalServerError.yaml
+++ b/openapi/components/responses/InternalServerError.yaml
@@ -3,3 +3,11 @@ content:
   application/problem+json:
     schema:
       $ref: ../schemas/Error.yaml
+    examples:
+      InternalServerError:
+        summary: Unexpected server error
+        dataValue:
+          type: about:blank
+          title: Internal Server Error
+          status: 500
+          instance: /orders
diff --git a/openapi/components/responses/MenuItemNotFound.yaml b/openapi/components/responses/MenuItemNotFound.yaml
new file mode 100644
index 0000000..11ee078
--- /dev/null
+++ b/openapi/components/responses/MenuItemNotFound.yaml
@@ -0,0 +1,13 @@
+description: Menu item not found.
+content:
+  application/problem+json:
+    schema:
+      $ref: ../schemas/Error.yaml
+    examples:
+      MenuItemNotFound:
+        summary: No menu item with this ID
+        dataValue:
+          type: about:blank
+          title: Menu item not found
+          status: 404
+          instance: /menu/prd_01h1s5z6vf2mm1mz3hevnn9va7
diff --git a/openapi/components/responses/NotFound.yaml b/openapi/components/responses/NotFound.yaml
index 5b507cb..71c6986 100644
--- a/openapi/components/responses/NotFound.yaml
+++ b/openapi/components/responses/NotFound.yaml
@@ -3,3 +3,11 @@ content:
   application/problem+json:
     schema:
       $ref: ../schemas/Error.yaml
+    examples:
+      NotFound:
+        summary: No resource at this path
+        dataValue:
+          type: about:blank
+          title: Cannot GET /.well-known/oauth-authorization-server
+          status: 404
+          instance: /.well-known/oauth-authorization-server
diff --git a/openapi/components/responses/OAuth2BadRequest.yaml b/openapi/components/responses/OAuth2BadRequest.yaml
index cae087a..195f78a 100644
--- a/openapi/components/responses/OAuth2BadRequest.yaml
+++ b/openapi/components/responses/OAuth2BadRequest.yaml
@@ -5,3 +5,9 @@ content:
   application/json:
     schema:
       $ref: ../schemas/OAuthError.yaml
+    examples:
+      InvalidGrant:
+        summary: Refresh token is invalid or expired
+        dataValue:
+          error: invalid_grant
+          error_description: Invalid refresh token
diff --git a/openapi/components/responses/OAuth2RegistrationBadRequest.yaml b/openapi/components/responses/OAuth2RegistrationBadRequest.yaml
new file mode 100644
index 0000000..f43c773
--- /dev/null
+++ b/openapi/components/responses/OAuth2RegistrationBadRequest.yaml
@@ -0,0 +1,11 @@
+description: Invalid client metadata (RFC 7591 Section 3.2.2).
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/OAuthError.yaml
+    examples:
+      InvalidClientMetadata:
+        summary: Requested scope does not exist
+        dataValue:
+          error: invalid_client_metadata
+          error_description: "scopes: Invalid enum value. Expected 'menu:read' | 'menu:write' | 'orders:read' | 'orders:write' | 'revenue:read', received 'admin'"
diff --git a/openapi/components/responses/OAuth2RegistrationUnauthorized.yaml b/openapi/components/responses/OAuth2RegistrationUnauthorized.yaml
new file mode 100644
index 0000000..e77fdf8
--- /dev/null
+++ b/openapi/components/responses/OAuth2RegistrationUnauthorized.yaml
@@ -0,0 +1,16 @@
+description: The registration access token is missing or invalid (RFC 7592 Section 2.1).
+headers:
+  WWW-Authenticate:
+    description: 'Authentication challenge, for example: `Bearer realm="redocly-cafe", error="invalid_token"`.'
+    schema:
+      type: string
+content:
+  application/json:
+    schema:
+      $ref: ../schemas/OAuthError.yaml
+    examples:
+      InvalidToken:
+        summary: Wrong registration access token
+        dataValue:
+          error: invalid_token
+          error_description: Invalid registration access token
diff --git a/openapi/components/responses/OAuth2ServerError.yaml b/openapi/components/responses/OAuth2ServerError.yaml
index d4fd6cc..73c539b 100644
--- a/openapi/components/responses/OAuth2ServerError.yaml
+++ b/openapi/components/responses/OAuth2ServerError.yaml
@@ -3,3 +3,9 @@ content:
   application/json:
     schema:
       $ref: ../schemas/OAuthError.yaml
+    examples:
+      ServerError:
+        summary: Unexpected server error
+        dataValue:
+          error: server_error
+          error_description: An internal error occurred
diff --git a/openapi/components/responses/OAuth2Unauthorized.yaml b/openapi/components/responses/OAuth2Unauthorized.yaml
index 091f071..79f935f 100644
--- a/openapi/components/responses/OAuth2Unauthorized.yaml
+++ b/openapi/components/responses/OAuth2Unauthorized.yaml
@@ -1,12 +1,18 @@
 description: |
-  Client authentication failed (`error: invalid_client`, RFC 6749 Section 5.2) or the presented bearer token is invalid (`error: invalid_token`, RFC 6750).
-  The response carries a `WWW-Authenticate` challenge naming the expected authentication scheme.
+  Client authentication failed (`error: invalid_client`, RFC 6749 Section 5.2).
+  When the client used HTTP Basic, the response carries a `WWW-Authenticate: Basic` challenge.
 headers:
   WWW-Authenticate:
-    description: 'Authentication challenge, for example: `Basic realm="redocly-cafe"` or `Bearer realm="redocly-cafe", error="invalid_token"`.'
+    description: 'Authentication challenge, for example: `Basic realm="redocly-cafe"`.'
     schema:
       type: string
 content:
   application/json:
     schema:
       $ref: ../schemas/OAuthError.yaml
+    examples:
+      InvalidClient:
+        summary: Wrong client_id or client_secret
+        dataValue:
+          error: invalid_client
+          error_description: Invalid client credentials
diff --git a/openapi/components/responses/OrderNotFound.yaml b/openapi/components/responses/OrderNotFound.yaml
new file mode 100644
index 0000000..4cfbcd1
--- /dev/null
+++ b/openapi/components/responses/OrderNotFound.yaml
@@ -0,0 +1,13 @@
+description: Order not found.
+content:
+  application/problem+json:
+    schema:
+      $ref: ../schemas/Error.yaml
+    examples:
+      OrderNotFound:
+        summary: No order with this ID
+        dataValue:
+          type: about:blank
+          title: Order not found
+          status: 404
+          instance: /orders/ord_01h1s5z6vf2mm1mz3hevnn9va7
diff --git a/openapi/components/responses/Unauthorized.yaml b/openapi/components/responses/Unauthorized.yaml
index 74c6f8c..8a7471e 100644
--- a/openapi/components/responses/Unauthorized.yaml
+++ b/openapi/components/responses/Unauthorized.yaml
@@ -3,3 +3,11 @@ content:
   application/problem+json:
     schema:
       $ref: ../schemas/Error.yaml
+    examples:
+      BearerTokenRequired:
+        summary: Missing access token
+        dataValue:
+          type: about:blank
+          title: Bearer token is required
+          status: 401
+          instance: /orders
diff --git a/openapi/components/schemas/AuthorizationServerMetadata.yaml b/openapi/components/schemas/AuthorizationServerMetadata.yaml
index c7aed6f..4709c28 100644
--- a/openapi/components/schemas/AuthorizationServerMetadata.yaml
+++ b/openapi/components/schemas/AuthorizationServerMetadata.yaml
@@ -5,20 +5,30 @@ properties:
     type: string
     format: uri
     description: The authorization server's issuer identifier.
+    examples:
+      - https://api.cafe.redocly.com
   authorization_endpoint:
     type: string
     format: uri
+    examples:
+      - https://api.cafe.redocly.com/oauth2/authorize
   token_endpoint:
     type: string
     format: uri
+    examples:
+      - https://api.cafe.redocly.com/oauth2/token
   registration_endpoint:
     type: string
     format: uri
     description: Dynamic client registration endpoint (RFC 7591).
+    examples:
+      - https://api.cafe.redocly.com/oauth2/register
   revocation_endpoint:
     type: string
     format: uri
     description: Token revocation endpoint (RFC 7009).
+    examples:
+      - https://api.cafe.redocly.com/oauth2/revoke
   scopes_supported:
     type: array
     items:
@@ -51,9 +61,13 @@ properties:
   authorization_response_iss_parameter_supported:
     type: boolean
     description: Whether authorization responses carry the `iss` parameter (RFC 9207).
+    examples:
+      - true
   service_documentation:
     type: string
     format: uri
+    examples:
+      - https://cafe.redocly.com/openapi/cafe
 required:
   - issuer
   - authorization_endpoint
diff --git a/openapi/components/schemas/Beverage.yaml b/openapi/components/schemas/Beverage.yaml
index 877d45c..0059efa 100644
--- a/openapi/components/schemas/Beverage.yaml
+++ b/openapi/components/schemas/Beverage.yaml
@@ -5,13 +5,19 @@ allOf:
         description: Menu item category.
         type: string
         const: beverage
+        examples:
+          - beverage
       volume:
         type: number
         description: Size of the beverage in milliliters.
         exclusiveMinimum: 0
+        examples:
+          - 240
       containsCaffeine:
         type: boolean
         description: Indicates if the beverage contains caffeine.
+        examples:
+          - true
     required:
       - category
       - volume
diff --git a/openapi/components/schemas/Dessert.yaml b/openapi/components/schemas/Dessert.yaml
index 8dc91ce..c739a06 100644
--- a/openapi/components/schemas/Dessert.yaml
+++ b/openapi/components/schemas/Dessert.yaml
@@ -5,10 +5,14 @@ allOf:
         description: Menu item category.
         type: string
         const: dessert
+        examples:
+          - dessert
       calories:
         type: number
         exclusiveMinimum: 0
         description: Amount of calories.
+        examples:
+          - 450
     required:
       - category
       - calories
diff --git a/openapi/components/schemas/Error.yaml b/openapi/components/schemas/Error.yaml
index 9c8f312..d64485d 100644
--- a/openapi/components/schemas/Error.yaml
+++ b/openapi/components/schemas/Error.yaml
@@ -5,9 +5,13 @@ properties:
     format: uri-reference
     description: URI reference that identifies the problem type.
     default: about:blank
+    examples:
+      - about:blank
   title:
     type: string
     description: Short summary of the problem type.
+    examples:
+      - Order not found
   status:
     type: integer
     format: int32
@@ -15,13 +19,16 @@ properties:
       HTTP status code generated by the origin server for this occurrence of the problem.
     minimum: 100
     exclusiveMaximum: 600
+    examples:
+      - 404
   instance:
     type: string
     format: uri-reference
     description: |
       URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type.
       Can be used to locate the root of this problem in the source code.
-    example: '/some/uri-reference#specific-occurrence-context'
+    examples:
+      - /orders/ord_01h1s5z6vf2mm1mz3hevnn9va7
   details:
     description: Additional error details.
     type: object
diff --git a/openapi/components/schemas/MenuBaseItem.yaml b/openapi/components/schemas/MenuBaseItem.yaml
index b683d8c..b738b0b 100644
--- a/openapi/components/schemas/MenuBaseItem.yaml
+++ b/openapi/components/schemas/MenuBaseItem.yaml
@@ -5,31 +5,42 @@ properties:
     type: string
     format: date-time
     readOnly: true
+    examples:
+      - '2026-10-14T09:01:29.000Z'
   updatedAt:
     description: Updated date.
     type: string
     format: date-time
     readOnly: true
+    examples:
+      - '2026-10-14T09:01:29.000Z'
   id:
     description: Menu item ID. Unique identifier prefixed with `prd_`.
     type: string
     readOnly: true
     pattern: ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
-    example: prd_01h1s5z6vf2mm1mz3hevnn9va7
+    examples:
+      - prd_0000000000seedcffee0000000
   object:
     description: Entity name.
     type: string
     const: menuItem
     readOnly: true
+    examples:
+      - menuItem
   name:
     description: Menu item name.
     type: string
     minLength: 1
     maxLength: 50
+    examples:
+      - coffee
   price:
     description: Price in cents.
     type: integer
     minimum: 0
+    examples:
+      - 5000
   photo:
     writeOnly: true
     type:
@@ -42,10 +53,14 @@ properties:
     type: string
     format: uri
     description: Photo URL of the menu item.
+    examples:
+      - https://api.cafe.redocly.com/menu-item-images/prd_0000000000seedcffee0000000
   photoTextDescription:
     type:
       - string
       - 'null'
+    examples:
+      - A warm cup of freshly brewed coffee
 required:
   - id
   - name
diff --git a/openapi/components/schemas/MenuItemList.yaml b/openapi/components/schemas/MenuItemList.yaml
index 4f3bd13..864747d 100644
--- a/openapi/components/schemas/MenuItemList.yaml
+++ b/openapi/components/schemas/MenuItemList.yaml
@@ -4,6 +4,8 @@ properties:
     type: string
     const: list
     description: Entity name.
+    examples:
+      - list
   page:
     $ref: ./Page.yaml
   items:
diff --git a/openapi/components/schemas/OAuth2Client.yaml b/openapi/components/schemas/OAuth2Client.yaml
index 120f088..83771e4 100644
--- a/openapi/components/schemas/OAuth2Client.yaml
+++ b/openapi/components/schemas/OAuth2Client.yaml
@@ -6,37 +6,53 @@ properties:
   client_id:
     type: string
     description: Client identifier issued by the authorization server.
+    examples:
+      - client_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
   client_secret:
     type: string
     description: Client secret issued by the authorization server.
       Store it securely.
+    examples:
+      - d2f724a5effb971bc979518f3c4d10b5dc77b40f16f688d1d26fc34b28887b2d
   client_id_issued_at:
     type: integer
     format: int64
     description: Time when the client_id is issued, represented as seconds since epoch (RFC 7591).
+    examples:
+      - 1771410038
   client_secret_expires_at:
     type: integer
     format: int64
     description: Time at which the client_secret expires, represented as seconds since epoch.
       `0` indicates the secret does not expire (RFC 7591).
+    examples:
+      - 0
   registration_client_uri:
     type: string
     format: uri
     description: URL of the client configuration endpoint for managing this client registration (RFC 7592).
+    examples:
+      - https://api.cafe.redocly.com/oauth2/register/client_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
   registration_access_token:
     type: string
     description: Bearer token for the client configuration endpoint (RFC 7592).
       Store it securely.
+    examples:
+      - 93e7525813f9ff98891772c80373b55bc7313b70496ad0656579de2def19d9bf
   client_name:
     type: string
     description: Client name (registered metadata).
       Omitted for clients registered without a name.
+    examples:
+      - pos-terminal
   redirect_uris:
     type: array
     items:
       type: string
       format: uri
     description: Registered redirect URIs.
+    examples:
+      - - https://api.cafe.redocly.com/callback
   grant_types:
     type: array
     items:
@@ -46,9 +62,14 @@ properties:
         - client_credentials
         - refresh_token
     description: Registered grant types.
+    examples:
+      - - authorization_code
+        - refresh_token
   scope:
     type: string
     description: Space-separated registered scopes.
+    examples:
+      - menu:read orders:read orders:write
   token_endpoint_auth_method:
     type: string
     enum:
@@ -57,6 +78,8 @@ properties:
     description: |
       Registered token endpoint authentication method. Defaults to `client_secret_basic` when not requested at registration (RFC 7591 Section 2).
       The token and revocation endpoints accept both methods for every client regardless.
+    examples:
+      - client_secret_basic
 # client_name is the only conditional field: it is omitted for clients
 # registered without a name. Everything else is always returned.
 required:
diff --git a/openapi/components/schemas/OAuthError.yaml b/openapi/components/schemas/OAuthError.yaml
index 0eba061..f25c396 100644
--- a/openapi/components/schemas/OAuthError.yaml
+++ b/openapi/components/schemas/OAuthError.yaml
@@ -19,8 +19,12 @@ properties:
       - invalid_token
       - access_denied
       - server_error
+    examples:
+      - invalid_grant
   error_description:
     type: string
     description: Human-readable explanation of the error.
+    examples:
+      - Invalid refresh token
 required:
   - error
diff --git a/openapi/components/schemas/Order.yaml b/openapi/components/schemas/Order.yaml
index 538776e..09ddb86 100644
--- a/openapi/components/schemas/Order.yaml
+++ b/openapi/components/schemas/Order.yaml
@@ -7,12 +7,15 @@ properties:
     format: ulid
     readOnly: true
     pattern: ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
-    example: ord_01h1s5z6vf2mm1mz3hevnn9va7
+    examples:
+      - ord_01h1s5z6vf2mm1mz3hevnn9va7
   object:
     description: Entity name.
     type: string
     const: order
     readOnly: true
+    examples:
+      - order
   customerName:
     description: |
       Name of the customer who placed the order.
@@ -21,6 +24,8 @@ properties:
     pattern: ^[A-Za-z]+(?:[\s'-][A-Za-z]+)*$
     minLength: 1
     maxLength: 100
+    examples:
+      - Mary Ann
   status:
     $ref: ./OrderStatus.yaml
     readOnly: true
@@ -29,16 +34,22 @@ properties:
     type: integer
     minimum: 0
     readOnly: true
+    examples:
+      - 10000
   createdAt:
     description: Created date.
     type: string
     format: date-time
     readOnly: true
+    examples:
+      - '2026-10-14T09:01:29.000Z'
   updatedAt:
     description: Updated date.
     type: string
     format: date-time
     readOnly: true
+    examples:
+      - '2026-10-14T09:01:29.000Z'
   orderItems:
     type: array
     description: List of items to include in the order.
@@ -50,19 +61,27 @@ properties:
           type: string
           format: ulid
           description: ID of the menu item to add to the order.
+          examples:
+            - prd_0000000000seedcffee0000000
         quantity:
           type: integer
           minimum: 1
           description: Quantity of the menu item.
+          examples:
+            - 2
         discount:
           type: integer
           minimum: 0
           description: Discount amount in cents (absolute value).
           default: 0
+          examples:
+            - 0
         comment:
           type: string
           maxLength: 500
           description: Optional comment for the order item (e.g., "No sugar").
+          examples:
+            - No sugar!
       required:
         - menuItemId
         - quantity
diff --git a/openapi/components/schemas/OrderItem.yaml b/openapi/components/schemas/OrderItem.yaml
index ae2989e..b5dd649 100644
--- a/openapi/components/schemas/OrderItem.yaml
+++ b/openapi/components/schemas/OrderItem.yaml
@@ -4,6 +4,8 @@ properties:
     type: string
     description: ID of the menu item to add to the order.
     writeOnly: true
+    examples:
+      - prd_0000000000seedcffee0000000
   menuItem:
     $ref: ./MenuItem.yaml
     readOnly: true
@@ -12,15 +14,21 @@ properties:
     type: integer
     minimum: 1
     description: Quantity of the menu item.
+    examples:
+      - 2
   discount:
     type: integer
     minimum: 0
     description: Discount amount in cents (absolute value).
     default: 0
+    examples:
+      - 0
   comment:
     type: string
     maxLength: 500
     description: Optional comment for the order item (e.g., "No sugar").
+    examples:
+      - No sugar!
 required:
   - menuItemId
   - quantity
diff --git a/openapi/components/schemas/OrderList.yaml b/openapi/components/schemas/OrderList.yaml
index 8fcd510..66167ca 100644
--- a/openapi/components/schemas/OrderList.yaml
+++ b/openapi/components/schemas/OrderList.yaml
@@ -4,6 +4,8 @@ properties:
     type: string
     const: list
     description: Entity name.
+    examples:
+      - list
   page:
     $ref: ./Page.yaml
   items:
diff --git a/openapi/components/schemas/OrderNotification.yaml b/openapi/components/schemas/OrderNotification.yaml
index c46fa9c..068c4dd 100644
--- a/openapi/components/schemas/OrderNotification.yaml
+++ b/openapi/components/schemas/OrderNotification.yaml
@@ -7,9 +7,13 @@ properties:
   orderId:
     type: string
     description: Unique order identifier.
+    examples:
+      - ord_01h1s5z6vf2mm1mz3hevnn9va7
   orderStatus:
     $ref: ./OrderStatus.yaml
   timestamp:
     type: string
     format: date-time
     description: When the event occurred.
+    examples:
+      - '2026-10-14T09:01:29.000Z'
diff --git a/openapi/components/schemas/OrderStatus.yaml b/openapi/components/schemas/OrderStatus.yaml
index 668df1f..af4bea0 100644
--- a/openapi/components/schemas/OrderStatus.yaml
+++ b/openapi/components/schemas/OrderStatus.yaml
@@ -5,3 +5,5 @@ enum:
   - preparing
   - completed
   - canceled
+examples:
+  - placed
diff --git a/openapi/components/schemas/Page.yaml b/openapi/components/schemas/Page.yaml
index e9433cc..90a40d1 100644
--- a/openapi/components/schemas/Page.yaml
+++ b/openapi/components/schemas/Page.yaml
@@ -30,6 +30,8 @@ properties:
     maximum: 100
     default: 10
     description: Value showing how many items are in the page limit.
+    examples:
+      - 10
 required:
   - nextPage
   - previousPage
diff --git a/openapi/components/schemas/RegisterClientMetadata.yaml b/openapi/components/schemas/RegisterClientMetadata.yaml
index 7f8eecc..260679b 100644
--- a/openapi/components/schemas/RegisterClientMetadata.yaml
+++ b/openapi/components/schemas/RegisterClientMetadata.yaml
@@ -6,13 +6,16 @@ properties:
   client_name:
     type: string
     description: Human-readable client name, displayed on the authorization consent screen.
+    examples:
+      - pos-terminal
   scope:
     type: string
     description: Space-separated list of scopes.
       Defaults to all available scopes.
     default: menu:read menu:write orders:read orders:write revenue:read
     pattern: '^(menu:read|menu:write|orders:read|orders:write|revenue:read)( (menu:read|menu:write|orders:read|orders:write|revenue:read))*$'
-    example: menu:read orders:read orders:write
+    examples:
+      - menu:read orders:read orders:write
   grant_types:
     type: array
     items:
@@ -39,3 +42,5 @@ properties:
       Requested client authentication method for the token endpoint, registered as client metadata and echoed in registration responses.
       Defaults to `client_secret_basic` (RFC 7591 Section 2).
       The token and revocation endpoints accept both methods for every client regardless.
+    examples:
+      - client_secret_basic
diff --git a/openapi/components/schemas/RevenueStatistics.yaml b/openapi/components/schemas/RevenueStatistics.yaml
index 4dd4792..95f2058 100644
--- a/openapi/components/schemas/RevenueStatistics.yaml
+++ b/openapi/components/schemas/RevenueStatistics.yaml
@@ -6,39 +6,57 @@ properties:
     format: float
     description: Total revenue in cents from completed orders.
     minimum: 0
+    examples:
+      - 135000
   averageOrderAmount:
     type: number
     format: float
     description: Average order amount in cents (calculated from completed orders only).
     minimum: 0
+    examples:
+      - 4500
   totalOrders:
     type: integer
     description: Total number of orders (all statuses) in the date range.
     minimum: 0
+    examples:
+      - 42
   placedOrders:
     type: integer
     description: Number of placed orders.
     minimum: 0
+    examples:
+      - 5
   preparingOrders:
     type: integer
     description: Number of preparing orders.
     minimum: 0
+    examples:
+      - 3
   completedOrders:
     type: integer
     description: Number of completed orders.
     minimum: 0
+    examples:
+      - 30
   canceledOrders:
     type: integer
     description: Number of canceled orders.
     minimum: 0
+    examples:
+      - 4
   startDate:
     type: string
     format: date-time
     description: Start date of the revenue calculation period.
+    examples:
+      - '2026-01-01T00:00:00.000Z'
   endDate:
     type: string
     format: date-time
     description: End date of the revenue calculation period.
+    examples:
+      - '2026-01-31T23:59:59.000Z'
 required:
   - revenue
   - averageOrderAmount
diff --git a/openapi/components/schemas/TokenResponse.yaml b/openapi/components/schemas/TokenResponse.yaml
index ec45d03..d4d7ef4 100644
--- a/openapi/components/schemas/TokenResponse.yaml
+++ b/openapi/components/schemas/TokenResponse.yaml
@@ -4,23 +4,31 @@ properties:
   access_token:
     type: string
     description: The issued access token (opaque string).
+    examples:
+      - ec85ccfb01243d256698f90e1703a41f32f0d5c9885544414798e7047e33662d
   token_type:
     type: string
     description: Type of the issued token.
     const: Bearer
+    examples:
+      - Bearer
   expires_in:
     type: integer
     description: Access token lifetime in seconds.
-    example: 3600
+    examples:
+      - 3600
   refresh_token:
     type: string
     description: |
       Refresh token, returned for the `authorization_code` grant when the client is registered for the `refresh_token` grant type, and on every refresh (tokens rotate on use).
       Never returned for the `client_credentials` grant (RFC 6749 Section 4.4.3).
+    examples:
+      - 915696fcff0a4f11a0cf51ba2b7eb8f1feaf586c6d517c56811773fdc1346f92
   scope:
     type: string
     description: Space-separated scopes granted to the token.
-    example: menu:read orders:read
+    examples:
+      - menu:read orders:read
 required:
   - access_token
   - token_type
diff --git a/openapi/components/schemas/UpdateClientObject.yaml b/openapi/components/schemas/UpdateClientObject.yaml
index 745abb2..0bb96f5 100644
--- a/openapi/components/schemas/UpdateClientObject.yaml
+++ b/openapi/components/schemas/UpdateClientObject.yaml
@@ -12,7 +12,11 @@ allOf:
         description: Required (RFC 7592 Section 2.2).
           Must match the client being updated.
           Credentials cannot be changed through this endpoint.
+        examples:
+          - client_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
       client_secret:
         type: string
         description: Optional.
           If present, must match the client's current secret.
+        examples:
+          - YOUR_CLIENT_SECRET
diff --git a/openapi/paths/menu-item-images_{menuItemId}.yaml b/openapi/paths/menu-item-images_{menuItemId}.yaml
index ea959d0..4b04de2 100644
--- a/openapi/paths/menu-item-images_{menuItemId}.yaml
+++ b/openapi/paths/menu-item-images_{menuItemId}.yaml
@@ -22,6 +22,6 @@ get:
             description: Alternative image text.
             type: string
     '404':
-      $ref: ../components/responses/NotFound.yaml
+      $ref: ../components/responses/MenuItemNotFound.yaml
     '500':
       $ref: ../components/responses/InternalServerError.yaml
diff --git a/openapi/paths/menu_{menuItemId}.yaml b/openapi/paths/menu_{menuItemId}.yaml
index d7caa01..634c258 100644
--- a/openapi/paths/menu_{menuItemId}.yaml
+++ b/openapi/paths/menu_{menuItemId}.yaml
@@ -19,6 +19,6 @@ delete:
     '403':
       $ref: ../components/responses/Forbidden.yaml
     '404':
-      $ref: ../components/responses/NotFound.yaml
+      $ref: ../components/responses/MenuItemNotFound.yaml
     '500':
       $ref: ../components/responses/InternalServerError.yaml
diff --git a/openapi/paths/oauth2_register.yaml b/openapi/paths/oauth2_register.yaml
index a036ad5..ac8b828 100644
--- a/openapi/paths/oauth2_register.yaml
+++ b/openapi/paths/oauth2_register.yaml
@@ -64,6 +64,6 @@ post:
           schema:
             $ref: ../components/schemas/OAuth2Client.yaml
     '400':
-      $ref: ../components/responses/OAuth2BadRequest.yaml
+      $ref: ../components/responses/OAuth2RegistrationBadRequest.yaml
     '500':
       $ref: ../components/responses/OAuth2ServerError.yaml
diff --git a/openapi/paths/oauth2_register_{clientId}.yaml b/openapi/paths/oauth2_register_{clientId}.yaml
index 21474e3..ef7fd05 100644
--- a/openapi/paths/oauth2_register_{clientId}.yaml
+++ b/openapi/paths/oauth2_register_{clientId}.yaml
@@ -19,7 +19,7 @@ get:
           schema:
             $ref: ../components/schemas/OAuth2Client.yaml
     '401':
-      $ref: ../components/responses/OAuth2Unauthorized.yaml
+      $ref: ../components/responses/OAuth2RegistrationUnauthorized.yaml
     '500':
       $ref: ../components/responses/OAuth2ServerError.yaml
 put:
@@ -62,9 +62,9 @@ put:
           schema:
             $ref: ../components/schemas/OAuth2Client.yaml
     '400':
-      $ref: ../components/responses/OAuth2BadRequest.yaml
+      $ref: ../components/responses/OAuth2RegistrationBadRequest.yaml
     '401':
-      $ref: ../components/responses/OAuth2Unauthorized.yaml
+      $ref: ../components/responses/OAuth2RegistrationUnauthorized.yaml
     '500':
       $ref: ../components/responses/OAuth2ServerError.yaml
 delete:
@@ -82,6 +82,6 @@ delete:
     '204':
       description: Client registration deleted.
     '401':
-      $ref: ../components/responses/OAuth2Unauthorized.yaml
+      $ref: ../components/responses/OAuth2RegistrationUnauthorized.yaml
     '500':
       $ref: ../components/responses/OAuth2ServerError.yaml
diff --git a/openapi/paths/oauth2_revoke.yaml b/openapi/paths/oauth2_revoke.yaml
index 0283fc1..5c935e2 100644
--- a/openapi/paths/oauth2_revoke.yaml
+++ b/openapi/paths/oauth2_revoke.yaml
@@ -25,20 +25,28 @@ post:
             token:
               type: string
               description: The access or refresh token to revoke.
+              examples:
+                - YOUR_ACCESS_TOKEN
             token_type_hint:
               type: string
               enum:
                 - access_token
                 - refresh_token
               description: Optional hint about the token type.
+              examples:
+                - access_token
             client_id:
               type: string
               description: Client identifier.
                 Omit when authenticating with HTTP Basic.
+              examples:
+                - client_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
             client_secret:
               type: string
               description: Client secret.
                 Omit when authenticating with HTTP Basic.
+              examples:
+                - YOUR_CLIENT_SECRET
           required:
             - token
         examples:
diff --git a/openapi/paths/oauth2_token.yaml b/openapi/paths/oauth2_token.yaml
index 64e0682..574b808 100644
--- a/openapi/paths/oauth2_token.yaml
+++ b/openapi/paths/oauth2_token.yaml
@@ -41,36 +41,52 @@ post:
                 - client_credentials
                 - refresh_token
               description: The OAuth2 grant type.
+              examples:
+                - client_credentials
             client_id:
               type: string
               description: Client identifier.
                 Omit when authenticating with HTTP Basic.
+              examples:
+                - client_fa18ff130e1a8f445509f7e5d1d97880
             client_secret:
               type: string
               description: Client secret.
                 Omit when authenticating with HTTP Basic.
+              examples:
+                - YOUR_CLIENT_SECRET
             code:
               type: string
               description: The authorization code (required for `authorization_code`).
+              examples:
+                - AUTHORIZATION_CODE
             redirect_uri:
               type: string
               format: uri
               description: Must match the redirect URI used in the authorization request.
                 Required for `authorization_code`).
+              examples:
+                - https://api.cafe.redocly.com/callback
             code_verifier:
               type: string
               minLength: 43
               maxLength: 128
               description: PKCE code verifier (RFC 7636)
                 Required when the authorization request included a `code_challenge`.
+              examples:
+                - dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
             refresh_token:
               type: string
               description: The refresh token.
                 Required for `refresh_token`.
+              examples:
+                - YOUR_REFRESH_TOKEN
             scope:
               type: string
               description: Space-separated scopes to request.
                 Defaults to the previously granted or registered scopes.
+              examples:
+                - menu:read orders:read
           required:
             - grant_type
         examples:
diff --git a/openapi/paths/order-items.yaml b/openapi/paths/order-items.yaml
index d5b7de8..eadbcf5 100644
--- a/openapi/paths/order-items.yaml
+++ b/openapi/paths/order-items.yaml
@@ -28,6 +28,6 @@ get:
     '403':
       $ref: ../components/responses/Forbidden.yaml
     '404':
-      $ref: ../components/responses/NotFound.yaml
+      $ref: ../components/responses/OrderNotFound.yaml
     '500':
       $ref: ../components/responses/InternalServerError.yaml
diff --git a/openapi/paths/orders_{orderId}.yaml b/openapi/paths/orders_{orderId}.yaml
index 48109bf..d1dad5b 100644
--- a/openapi/paths/orders_{orderId}.yaml
+++ b/openapi/paths/orders_{orderId}.yaml
@@ -38,7 +38,7 @@ get:
     '403':
       $ref: ../components/responses/Forbidden.yaml
     '404':
-      $ref: ../components/responses/NotFound.yaml
+      $ref: ../components/responses/OrderNotFound.yaml
     '500':
       $ref: ../components/responses/InternalServerError.yaml
 patch:
@@ -95,7 +95,7 @@ patch:
     '403':
       $ref: ../components/responses/Forbidden.yaml
     '404':
-      $ref: ../components/responses/NotFound.yaml
+      $ref: ../components/responses/OrderNotFound.yaml
     '500':
       $ref: ../components/responses/InternalServerError.yaml
 delete:
@@ -121,6 +121,6 @@ delete:
     '403':
       $ref: ../components/responses/Forbidden.yaml
     '404':
-      $ref: ../components/responses/NotFound.yaml
+      $ref: ../components/responses/OrderNotFound.yaml
     '500':
       $ref: ../components/responses/InternalServerError.yaml
diff --git a/redocly.yaml b/redocly.yaml
index c7373f6..8e16256 100644
--- a/redocly.yaml
+++ b/redocly.yaml
@@ -4,6 +4,25 @@ apis:
   cafe-api:
     root: "./openapi/cafe.yaml"
     rules:
+      # Rules of the Reunite project starter template, so Cafe stays usable as starter content.
+      operation-tag-defined: error
+      no-invalid-schema-examples: error
+      no-invalid-media-type-examples: error
+      scalar-property-missing-example: error
+      rule/operation-summary-sentence-case:
+        subject:
+          type: Operation
+          property: summary
+        message: Operation summary must be sentence cased.
+        assertions:
+          pattern: /^[A-Z]\S*(\s+(?!\(?[A-Z][a-z]+\b)\S+)*$/ # Sentence case; acronyms like OAuth2 and RFC are allowed
+      rule/example-summary-sentence-case:
+        subject:
+          type: Example
+          property: summary
+        message: Example summary must be sentence cased.
+        assertions:
+          pattern: /^[A-Z]\S*(\s+(?!\(?[A-Z][a-z]+\b)\S+)*$/ # Sentence case; acronyms like OAuth2 and RFC are allowed
       rule/operation-summary:
         subject:
           type: Operation

From 3a73a432ed02f6fa921ae8caef8b98ae67793c3f Mon Sep 17 00:00:00 2001
From: Vadym Vasylyshyn <51933329+vadyvas@users.noreply.github.com>
Date: Wed, 14 Oct 2026 18:35:49 +0300
Subject: [PATCH 2/7] fix(openapi): use dates as the revenue example summaries

---
 openapi/paths/revenue.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/openapi/paths/revenue.yaml b/openapi/paths/revenue.yaml
index b5bc42e..ad38010 100644
--- a/openapi/paths/revenue.yaml
+++ b/openapi/paths/revenue.yaml
@@ -22,7 +22,7 @@ get:
         format: date-time
       examples:
         StartOfJanuary:
-          summary: Start of January 2026
+          summary: January 1, 2026
           dataValue: '2026-01-01T00:00:00Z'
     - name: endDate
       in: query
@@ -35,7 +35,7 @@ get:
         format: date-time
       examples:
         EndOfJanuary:
-          summary: End of January 2026
+          summary: January 31, 2026
           dataValue: '2026-01-31T23:59:59Z'
   responses:
     '200':

From 431d79e463cd916ca18ff388de04ff001120318e Mon Sep 17 00:00:00 2001
From: Vadym Vasylyshyn <51933329+vadyvas@users.noreply.github.com>
Date: Wed, 14 Oct 2026 18:35:49 +0300
Subject: [PATCH 3/7] chore(openapi): remove the duplicate OAuth2BadRequest
 example

---
 openapi/components/responses/OAuth2BadRequest.yaml | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/openapi/components/responses/OAuth2BadRequest.yaml b/openapi/components/responses/OAuth2BadRequest.yaml
index 195f78a..cae087a 100644
--- a/openapi/components/responses/OAuth2BadRequest.yaml
+++ b/openapi/components/responses/OAuth2BadRequest.yaml
@@ -5,9 +5,3 @@ content:
   application/json:
     schema:
       $ref: ../schemas/OAuthError.yaml
-    examples:
-      InvalidGrant:
-        summary: Refresh token is invalid or expired
-        dataValue:
-          error: invalid_grant
-          error_description: Invalid refresh token

From 7a4ff4ea02dcf4bfa9e9e4918493c2de177338bc Mon Sep 17 00:00:00 2001
From: Vadym Vasylyshyn <51933329+vadyvas@users.noreply.github.com>
Date: Thu, 15 Oct 2026 12:23:46 +0300
Subject: [PATCH 4/7] chore: move rules to the root

---
 redocly.yaml | 60 ++++++++++++++++++++++++++--------------------------
 1 file changed, 30 insertions(+), 30 deletions(-)

diff --git a/redocly.yaml b/redocly.yaml
index 8e16256..1092fe8 100644
--- a/redocly.yaml
+++ b/redocly.yaml
@@ -3,37 +3,37 @@ extends:
 apis:
   cafe-api:
     root: "./openapi/cafe.yaml"
-    rules:
-      # Rules of the Reunite project starter template, so Cafe stays usable as starter content.
-      operation-tag-defined: error
-      no-invalid-schema-examples: error
-      no-invalid-media-type-examples: error
-      scalar-property-missing-example: error
-      rule/operation-summary-sentence-case:
-        subject:
-          type: Operation
-          property: summary
-        message: Operation summary must be sentence cased.
-        assertions:
-          pattern: /^[A-Z]\S*(\s+(?!\(?[A-Z][a-z]+\b)\S+)*$/ # Sentence case; acronyms like OAuth2 and RFC are allowed
-      rule/example-summary-sentence-case:
-        subject:
-          type: Example
-          property: summary
-        message: Example summary must be sentence cased.
-        assertions:
-          pattern: /^[A-Z]\S*(\s+(?!\(?[A-Z][a-z]+\b)\S+)*$/ # Sentence case; acronyms like OAuth2 and RFC are allowed
-      rule/operation-summary:
-        subject:
-          type: Operation
-          property: summary
-        where:
-          - subject:
-              type: Paths
-            assertions:
-              defined: true
+
+rules:
+  operation-tag-defined: error
+  no-invalid-schema-examples: error
+  no-invalid-media-type-examples: error
+  scalar-property-missing-example: error
+  rule/operation-summary-sentence-case:
+    subject:
+      type: Operation
+      property: summary
+    message: Operation summary must be sentence cased.
+    assertions:
+      pattern: /^[A-Z]\S*(\s+(?!\(?[A-Z][a-z]+\b)\S+)*$/ # Sentence case; acronyms like OAuth2 and RFC are allowed
+  rule/example-summary-sentence-case:
+    subject:
+      type: Example
+      property: summary
+    message: Example summary must be sentence cased.
+    assertions:
+      pattern: /^[A-Z]\S*(\s+(?!\(?[A-Z][a-z]+\b)\S+)*$/ # Sentence case; acronyms like OAuth2 and RFC are allowed
+  rule/operation-summary:
+    subject:
+      type: Operation
+      property: summary
+    where:
+      - subject:
+          type: Paths
         assertions:
-          pattern: /^(Create|Get|Retrieve|Replace|Update|Delete|Login|Send|Callback|Cancel|List|Partially update|Revoke).*[^\.]$/
+          defined: true
+    assertions:
+      pattern: /^(Create|Get|Retrieve|Replace|Update|Delete|Login|Send|Callback|Cancel|List|Partially update|Revoke).*[^\.]$/
 
 logo:
   srcSet: "./images/cafe-logo-black.svg light, ./images/cafe-logo-white.svg dark"

From 0a6640017f6f8c859c58464c6effe1b98c30fbea Mon Sep 17 00:00:00 2001
From: Vadym Vasylyshyn <51933329+vadyvas@users.noreply.github.com>
Date: Mon, 19 Oct 2026 17:50:37 +0300
Subject: [PATCH 5/7] chore: revert schema examples

---
 .../schemas/AuthorizationServerMetadata.yaml  | 14 -----------
 openapi/components/schemas/Beverage.yaml      |  6 -----
 openapi/components/schemas/Dessert.yaml       |  4 ----
 openapi/components/schemas/Error.yaml         |  9 +-------
 openapi/components/schemas/MenuBaseItem.yaml  | 17 +-------------
 openapi/components/schemas/MenuItemList.yaml  |  2 --
 openapi/components/schemas/OAuth2Client.yaml  | 23 -------------------
 openapi/components/schemas/OAuthError.yaml    |  4 ----
 openapi/components/schemas/Order.yaml         | 21 +----------------
 openapi/components/schemas/OrderItem.yaml     |  8 -------
 openapi/components/schemas/OrderList.yaml     |  2 --
 .../components/schemas/OrderNotification.yaml |  4 ----
 openapi/components/schemas/OrderStatus.yaml   |  2 --
 openapi/components/schemas/Page.yaml          |  2 --
 .../schemas/RegisterClientMetadata.yaml       |  7 +-----
 .../components/schemas/RevenueStatistics.yaml | 18 ---------------
 openapi/components/schemas/TokenResponse.yaml | 12 ++--------
 .../schemas/UpdateClientObject.yaml           |  4 ----
 redocly.yaml                                  |  5 ++--
 19 files changed, 8 insertions(+), 156 deletions(-)

diff --git a/openapi/components/schemas/AuthorizationServerMetadata.yaml b/openapi/components/schemas/AuthorizationServerMetadata.yaml
index 4709c28..c7aed6f 100644
--- a/openapi/components/schemas/AuthorizationServerMetadata.yaml
+++ b/openapi/components/schemas/AuthorizationServerMetadata.yaml
@@ -5,30 +5,20 @@ properties:
     type: string
     format: uri
     description: The authorization server's issuer identifier.
-    examples:
-      - https://api.cafe.redocly.com
   authorization_endpoint:
     type: string
     format: uri
-    examples:
-      - https://api.cafe.redocly.com/oauth2/authorize
   token_endpoint:
     type: string
     format: uri
-    examples:
-      - https://api.cafe.redocly.com/oauth2/token
   registration_endpoint:
     type: string
     format: uri
     description: Dynamic client registration endpoint (RFC 7591).
-    examples:
-      - https://api.cafe.redocly.com/oauth2/register
   revocation_endpoint:
     type: string
     format: uri
     description: Token revocation endpoint (RFC 7009).
-    examples:
-      - https://api.cafe.redocly.com/oauth2/revoke
   scopes_supported:
     type: array
     items:
@@ -61,13 +51,9 @@ properties:
   authorization_response_iss_parameter_supported:
     type: boolean
     description: Whether authorization responses carry the `iss` parameter (RFC 9207).
-    examples:
-      - true
   service_documentation:
     type: string
     format: uri
-    examples:
-      - https://cafe.redocly.com/openapi/cafe
 required:
   - issuer
   - authorization_endpoint
diff --git a/openapi/components/schemas/Beverage.yaml b/openapi/components/schemas/Beverage.yaml
index 0059efa..877d45c 100644
--- a/openapi/components/schemas/Beverage.yaml
+++ b/openapi/components/schemas/Beverage.yaml
@@ -5,19 +5,13 @@ allOf:
         description: Menu item category.
         type: string
         const: beverage
-        examples:
-          - beverage
       volume:
         type: number
         description: Size of the beverage in milliliters.
         exclusiveMinimum: 0
-        examples:
-          - 240
       containsCaffeine:
         type: boolean
         description: Indicates if the beverage contains caffeine.
-        examples:
-          - true
     required:
       - category
       - volume
diff --git a/openapi/components/schemas/Dessert.yaml b/openapi/components/schemas/Dessert.yaml
index c739a06..8dc91ce 100644
--- a/openapi/components/schemas/Dessert.yaml
+++ b/openapi/components/schemas/Dessert.yaml
@@ -5,14 +5,10 @@ allOf:
         description: Menu item category.
         type: string
         const: dessert
-        examples:
-          - dessert
       calories:
         type: number
         exclusiveMinimum: 0
         description: Amount of calories.
-        examples:
-          - 450
     required:
       - category
       - calories
diff --git a/openapi/components/schemas/Error.yaml b/openapi/components/schemas/Error.yaml
index d64485d..9c8f312 100644
--- a/openapi/components/schemas/Error.yaml
+++ b/openapi/components/schemas/Error.yaml
@@ -5,13 +5,9 @@ properties:
     format: uri-reference
     description: URI reference that identifies the problem type.
     default: about:blank
-    examples:
-      - about:blank
   title:
     type: string
     description: Short summary of the problem type.
-    examples:
-      - Order not found
   status:
     type: integer
     format: int32
@@ -19,16 +15,13 @@ properties:
       HTTP status code generated by the origin server for this occurrence of the problem.
     minimum: 100
     exclusiveMaximum: 600
-    examples:
-      - 404
   instance:
     type: string
     format: uri-reference
     description: |
       URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type.
       Can be used to locate the root of this problem in the source code.
-    examples:
-      - /orders/ord_01h1s5z6vf2mm1mz3hevnn9va7
+    example: '/some/uri-reference#specific-occurrence-context'
   details:
     description: Additional error details.
     type: object
diff --git a/openapi/components/schemas/MenuBaseItem.yaml b/openapi/components/schemas/MenuBaseItem.yaml
index b738b0b..b683d8c 100644
--- a/openapi/components/schemas/MenuBaseItem.yaml
+++ b/openapi/components/schemas/MenuBaseItem.yaml
@@ -5,42 +5,31 @@ properties:
     type: string
     format: date-time
     readOnly: true
-    examples:
-      - '2026-10-14T09:01:29.000Z'
   updatedAt:
     description: Updated date.
     type: string
     format: date-time
     readOnly: true
-    examples:
-      - '2026-10-14T09:01:29.000Z'
   id:
     description: Menu item ID. Unique identifier prefixed with `prd_`.
     type: string
     readOnly: true
     pattern: ^prd_[0-9abcdefghjkmnpqrstvwxyz]{26}$
-    examples:
-      - prd_0000000000seedcffee0000000
+    example: prd_01h1s5z6vf2mm1mz3hevnn9va7
   object:
     description: Entity name.
     type: string
     const: menuItem
     readOnly: true
-    examples:
-      - menuItem
   name:
     description: Menu item name.
     type: string
     minLength: 1
     maxLength: 50
-    examples:
-      - coffee
   price:
     description: Price in cents.
     type: integer
     minimum: 0
-    examples:
-      - 5000
   photo:
     writeOnly: true
     type:
@@ -53,14 +42,10 @@ properties:
     type: string
     format: uri
     description: Photo URL of the menu item.
-    examples:
-      - https://api.cafe.redocly.com/menu-item-images/prd_0000000000seedcffee0000000
   photoTextDescription:
     type:
       - string
       - 'null'
-    examples:
-      - A warm cup of freshly brewed coffee
 required:
   - id
   - name
diff --git a/openapi/components/schemas/MenuItemList.yaml b/openapi/components/schemas/MenuItemList.yaml
index 864747d..4f3bd13 100644
--- a/openapi/components/schemas/MenuItemList.yaml
+++ b/openapi/components/schemas/MenuItemList.yaml
@@ -4,8 +4,6 @@ properties:
     type: string
     const: list
     description: Entity name.
-    examples:
-      - list
   page:
     $ref: ./Page.yaml
   items:
diff --git a/openapi/components/schemas/OAuth2Client.yaml b/openapi/components/schemas/OAuth2Client.yaml
index 83771e4..120f088 100644
--- a/openapi/components/schemas/OAuth2Client.yaml
+++ b/openapi/components/schemas/OAuth2Client.yaml
@@ -6,53 +6,37 @@ properties:
   client_id:
     type: string
     description: Client identifier issued by the authorization server.
-    examples:
-      - client_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
   client_secret:
     type: string
     description: Client secret issued by the authorization server.
       Store it securely.
-    examples:
-      - d2f724a5effb971bc979518f3c4d10b5dc77b40f16f688d1d26fc34b28887b2d
   client_id_issued_at:
     type: integer
     format: int64
     description: Time when the client_id is issued, represented as seconds since epoch (RFC 7591).
-    examples:
-      - 1771410038
   client_secret_expires_at:
     type: integer
     format: int64
     description: Time at which the client_secret expires, represented as seconds since epoch.
       `0` indicates the secret does not expire (RFC 7591).
-    examples:
-      - 0
   registration_client_uri:
     type: string
     format: uri
     description: URL of the client configuration endpoint for managing this client registration (RFC 7592).
-    examples:
-      - https://api.cafe.redocly.com/oauth2/register/client_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
   registration_access_token:
     type: string
     description: Bearer token for the client configuration endpoint (RFC 7592).
       Store it securely.
-    examples:
-      - 93e7525813f9ff98891772c80373b55bc7313b70496ad0656579de2def19d9bf
   client_name:
     type: string
     description: Client name (registered metadata).
       Omitted for clients registered without a name.
-    examples:
-      - pos-terminal
   redirect_uris:
     type: array
     items:
       type: string
       format: uri
     description: Registered redirect URIs.
-    examples:
-      - - https://api.cafe.redocly.com/callback
   grant_types:
     type: array
     items:
@@ -62,14 +46,9 @@ properties:
         - client_credentials
         - refresh_token
     description: Registered grant types.
-    examples:
-      - - authorization_code
-        - refresh_token
   scope:
     type: string
     description: Space-separated registered scopes.
-    examples:
-      - menu:read orders:read orders:write
   token_endpoint_auth_method:
     type: string
     enum:
@@ -78,8 +57,6 @@ properties:
     description: |
       Registered token endpoint authentication method. Defaults to `client_secret_basic` when not requested at registration (RFC 7591 Section 2).
       The token and revocation endpoints accept both methods for every client regardless.
-    examples:
-      - client_secret_basic
 # client_name is the only conditional field: it is omitted for clients
 # registered without a name. Everything else is always returned.
 required:
diff --git a/openapi/components/schemas/OAuthError.yaml b/openapi/components/schemas/OAuthError.yaml
index f25c396..0eba061 100644
--- a/openapi/components/schemas/OAuthError.yaml
+++ b/openapi/components/schemas/OAuthError.yaml
@@ -19,12 +19,8 @@ properties:
       - invalid_token
       - access_denied
       - server_error
-    examples:
-      - invalid_grant
   error_description:
     type: string
     description: Human-readable explanation of the error.
-    examples:
-      - Invalid refresh token
 required:
   - error
diff --git a/openapi/components/schemas/Order.yaml b/openapi/components/schemas/Order.yaml
index 09ddb86..538776e 100644
--- a/openapi/components/schemas/Order.yaml
+++ b/openapi/components/schemas/Order.yaml
@@ -7,15 +7,12 @@ properties:
     format: ulid
     readOnly: true
     pattern: ^ord_[0-9abcdefghjkmnpqrstvwxyz]{26}$
-    examples:
-      - ord_01h1s5z6vf2mm1mz3hevnn9va7
+    example: ord_01h1s5z6vf2mm1mz3hevnn9va7
   object:
     description: Entity name.
     type: string
     const: order
     readOnly: true
-    examples:
-      - order
   customerName:
     description: |
       Name of the customer who placed the order.
@@ -24,8 +21,6 @@ properties:
     pattern: ^[A-Za-z]+(?:[\s'-][A-Za-z]+)*$
     minLength: 1
     maxLength: 100
-    examples:
-      - Mary Ann
   status:
     $ref: ./OrderStatus.yaml
     readOnly: true
@@ -34,22 +29,16 @@ properties:
     type: integer
     minimum: 0
     readOnly: true
-    examples:
-      - 10000
   createdAt:
     description: Created date.
     type: string
     format: date-time
     readOnly: true
-    examples:
-      - '2026-10-14T09:01:29.000Z'
   updatedAt:
     description: Updated date.
     type: string
     format: date-time
     readOnly: true
-    examples:
-      - '2026-10-14T09:01:29.000Z'
   orderItems:
     type: array
     description: List of items to include in the order.
@@ -61,27 +50,19 @@ properties:
           type: string
           format: ulid
           description: ID of the menu item to add to the order.
-          examples:
-            - prd_0000000000seedcffee0000000
         quantity:
           type: integer
           minimum: 1
           description: Quantity of the menu item.
-          examples:
-            - 2
         discount:
           type: integer
           minimum: 0
           description: Discount amount in cents (absolute value).
           default: 0
-          examples:
-            - 0
         comment:
           type: string
           maxLength: 500
           description: Optional comment for the order item (e.g., "No sugar").
-          examples:
-            - No sugar!
       required:
         - menuItemId
         - quantity
diff --git a/openapi/components/schemas/OrderItem.yaml b/openapi/components/schemas/OrderItem.yaml
index b5dd649..ae2989e 100644
--- a/openapi/components/schemas/OrderItem.yaml
+++ b/openapi/components/schemas/OrderItem.yaml
@@ -4,8 +4,6 @@ properties:
     type: string
     description: ID of the menu item to add to the order.
     writeOnly: true
-    examples:
-      - prd_0000000000seedcffee0000000
   menuItem:
     $ref: ./MenuItem.yaml
     readOnly: true
@@ -14,21 +12,15 @@ properties:
     type: integer
     minimum: 1
     description: Quantity of the menu item.
-    examples:
-      - 2
   discount:
     type: integer
     minimum: 0
     description: Discount amount in cents (absolute value).
     default: 0
-    examples:
-      - 0
   comment:
     type: string
     maxLength: 500
     description: Optional comment for the order item (e.g., "No sugar").
-    examples:
-      - No sugar!
 required:
   - menuItemId
   - quantity
diff --git a/openapi/components/schemas/OrderList.yaml b/openapi/components/schemas/OrderList.yaml
index 66167ca..8fcd510 100644
--- a/openapi/components/schemas/OrderList.yaml
+++ b/openapi/components/schemas/OrderList.yaml
@@ -4,8 +4,6 @@ properties:
     type: string
     const: list
     description: Entity name.
-    examples:
-      - list
   page:
     $ref: ./Page.yaml
   items:
diff --git a/openapi/components/schemas/OrderNotification.yaml b/openapi/components/schemas/OrderNotification.yaml
index 068c4dd..c46fa9c 100644
--- a/openapi/components/schemas/OrderNotification.yaml
+++ b/openapi/components/schemas/OrderNotification.yaml
@@ -7,13 +7,9 @@ properties:
   orderId:
     type: string
     description: Unique order identifier.
-    examples:
-      - ord_01h1s5z6vf2mm1mz3hevnn9va7
   orderStatus:
     $ref: ./OrderStatus.yaml
   timestamp:
     type: string
     format: date-time
     description: When the event occurred.
-    examples:
-      - '2026-10-14T09:01:29.000Z'
diff --git a/openapi/components/schemas/OrderStatus.yaml b/openapi/components/schemas/OrderStatus.yaml
index af4bea0..668df1f 100644
--- a/openapi/components/schemas/OrderStatus.yaml
+++ b/openapi/components/schemas/OrderStatus.yaml
@@ -5,5 +5,3 @@ enum:
   - preparing
   - completed
   - canceled
-examples:
-  - placed
diff --git a/openapi/components/schemas/Page.yaml b/openapi/components/schemas/Page.yaml
index 90a40d1..e9433cc 100644
--- a/openapi/components/schemas/Page.yaml
+++ b/openapi/components/schemas/Page.yaml
@@ -30,8 +30,6 @@ properties:
     maximum: 100
     default: 10
     description: Value showing how many items are in the page limit.
-    examples:
-      - 10
 required:
   - nextPage
   - previousPage
diff --git a/openapi/components/schemas/RegisterClientMetadata.yaml b/openapi/components/schemas/RegisterClientMetadata.yaml
index 260679b..7f8eecc 100644
--- a/openapi/components/schemas/RegisterClientMetadata.yaml
+++ b/openapi/components/schemas/RegisterClientMetadata.yaml
@@ -6,16 +6,13 @@ properties:
   client_name:
     type: string
     description: Human-readable client name, displayed on the authorization consent screen.
-    examples:
-      - pos-terminal
   scope:
     type: string
     description: Space-separated list of scopes.
       Defaults to all available scopes.
     default: menu:read menu:write orders:read orders:write revenue:read
     pattern: '^(menu:read|menu:write|orders:read|orders:write|revenue:read)( (menu:read|menu:write|orders:read|orders:write|revenue:read))*$'
-    examples:
-      - menu:read orders:read orders:write
+    example: menu:read orders:read orders:write
   grant_types:
     type: array
     items:
@@ -42,5 +39,3 @@ properties:
       Requested client authentication method for the token endpoint, registered as client metadata and echoed in registration responses.
       Defaults to `client_secret_basic` (RFC 7591 Section 2).
       The token and revocation endpoints accept both methods for every client regardless.
-    examples:
-      - client_secret_basic
diff --git a/openapi/components/schemas/RevenueStatistics.yaml b/openapi/components/schemas/RevenueStatistics.yaml
index 95f2058..4dd4792 100644
--- a/openapi/components/schemas/RevenueStatistics.yaml
+++ b/openapi/components/schemas/RevenueStatistics.yaml
@@ -6,57 +6,39 @@ properties:
     format: float
     description: Total revenue in cents from completed orders.
     minimum: 0
-    examples:
-      - 135000
   averageOrderAmount:
     type: number
     format: float
     description: Average order amount in cents (calculated from completed orders only).
     minimum: 0
-    examples:
-      - 4500
   totalOrders:
     type: integer
     description: Total number of orders (all statuses) in the date range.
     minimum: 0
-    examples:
-      - 42
   placedOrders:
     type: integer
     description: Number of placed orders.
     minimum: 0
-    examples:
-      - 5
   preparingOrders:
     type: integer
     description: Number of preparing orders.
     minimum: 0
-    examples:
-      - 3
   completedOrders:
     type: integer
     description: Number of completed orders.
     minimum: 0
-    examples:
-      - 30
   canceledOrders:
     type: integer
     description: Number of canceled orders.
     minimum: 0
-    examples:
-      - 4
   startDate:
     type: string
     format: date-time
     description: Start date of the revenue calculation period.
-    examples:
-      - '2026-01-01T00:00:00.000Z'
   endDate:
     type: string
     format: date-time
     description: End date of the revenue calculation period.
-    examples:
-      - '2026-01-31T23:59:59.000Z'
 required:
   - revenue
   - averageOrderAmount
diff --git a/openapi/components/schemas/TokenResponse.yaml b/openapi/components/schemas/TokenResponse.yaml
index d4d7ef4..ec45d03 100644
--- a/openapi/components/schemas/TokenResponse.yaml
+++ b/openapi/components/schemas/TokenResponse.yaml
@@ -4,31 +4,23 @@ properties:
   access_token:
     type: string
     description: The issued access token (opaque string).
-    examples:
-      - ec85ccfb01243d256698f90e1703a41f32f0d5c9885544414798e7047e33662d
   token_type:
     type: string
     description: Type of the issued token.
     const: Bearer
-    examples:
-      - Bearer
   expires_in:
     type: integer
     description: Access token lifetime in seconds.
-    examples:
-      - 3600
+    example: 3600
   refresh_token:
     type: string
     description: |
       Refresh token, returned for the `authorization_code` grant when the client is registered for the `refresh_token` grant type, and on every refresh (tokens rotate on use).
       Never returned for the `client_credentials` grant (RFC 6749 Section 4.4.3).
-    examples:
-      - 915696fcff0a4f11a0cf51ba2b7eb8f1feaf586c6d517c56811773fdc1346f92
   scope:
     type: string
     description: Space-separated scopes granted to the token.
-    examples:
-      - menu:read orders:read
+    example: menu:read orders:read
 required:
   - access_token
   - token_type
diff --git a/openapi/components/schemas/UpdateClientObject.yaml b/openapi/components/schemas/UpdateClientObject.yaml
index 0bb96f5..745abb2 100644
--- a/openapi/components/schemas/UpdateClientObject.yaml
+++ b/openapi/components/schemas/UpdateClientObject.yaml
@@ -12,11 +12,7 @@ allOf:
         description: Required (RFC 7592 Section 2.2).
           Must match the client being updated.
           Credentials cannot be changed through this endpoint.
-        examples:
-          - client_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
       client_secret:
         type: string
         description: Optional.
           If present, must match the client's current secret.
-        examples:
-          - YOUR_CLIENT_SECRET
diff --git a/redocly.yaml b/redocly.yaml
index 1092fe8..6b7b7f3 100644
--- a/redocly.yaml
+++ b/redocly.yaml
@@ -8,21 +8,20 @@ rules:
   operation-tag-defined: error
   no-invalid-schema-examples: error
   no-invalid-media-type-examples: error
-  scalar-property-missing-example: error
   rule/operation-summary-sentence-case:
     subject:
       type: Operation
       property: summary
     message: Operation summary must be sentence cased.
     assertions:
-      pattern: /^[A-Z]\S*(\s+(?!\(?[A-Z][a-z]+\b)\S+)*$/ # Sentence case; acronyms like OAuth2 and RFC are allowed
+      pattern: /^([A-Z]{2,}|[A-Z][^A-Z]*|OAuth2)(?=\s|$)(\s+\(?(?:[A-Z]{2,}|[^A-Z]*|OAuth2)\)?(?=\s|$))*$/
   rule/example-summary-sentence-case:
     subject:
       type: Example
       property: summary
     message: Example summary must be sentence cased.
     assertions:
-      pattern: /^[A-Z]\S*(\s+(?!\(?[A-Z][a-z]+\b)\S+)*$/ # Sentence case; acronyms like OAuth2 and RFC are allowed
+      pattern: /^([A-Z]{2,}|[A-Z][^A-Z]*|OAuth2)(?=\s|$)(\s+\(?(?:[A-Z]{2,}|[^A-Z]*|OAuth2)\)?(?=\s|$))*$/
   rule/operation-summary:
     subject:
       type: Operation

From e14c6cd9fba1dc34f9c55e2e5782d860b7bf7ab1 Mon Sep 17 00:00:00 2001
From: Vadym Vasylyshyn <51933329+vadyvas@users.noreply.github.com>
Date: Mon, 19 Oct 2026 18:02:30 +0300
Subject: [PATCH 6/7] chore: remove duplication

---
 .../components/responses/MenuItemNotFound.yaml   | 13 -------------
 openapi/components/responses/NotFound.yaml       | 14 ++++++++++++++
 .../components/responses/OAuth2BadRequest.yaml   | 11 +++++++++++
 .../responses/OAuth2RegistrationBadRequest.yaml  | 11 -----------
 .../OAuth2RegistrationUnauthorized.yaml          | 16 ----------------
 .../components/responses/OAuth2Unauthorized.yaml | 11 ++++++++---
 openapi/components/responses/OrderNotFound.yaml  | 13 -------------
 openapi/paths/menu-item-images_{menuItemId}.yaml |  2 +-
 openapi/paths/menu_{menuItemId}.yaml             |  2 +-
 openapi/paths/oauth2_register.yaml               |  2 +-
 openapi/paths/oauth2_register_{clientId}.yaml    |  8 ++++----
 openapi/paths/oauth2_revoke.yaml                 |  8 --------
 openapi/paths/oauth2_token.yaml                  | 16 ----------------
 openapi/paths/order-items.yaml                   |  2 +-
 openapi/paths/orders_{orderId}.yaml              |  6 +++---
 15 files changed, 44 insertions(+), 91 deletions(-)
 delete mode 100644 openapi/components/responses/MenuItemNotFound.yaml
 delete mode 100644 openapi/components/responses/OAuth2RegistrationBadRequest.yaml
 delete mode 100644 openapi/components/responses/OAuth2RegistrationUnauthorized.yaml
 delete mode 100644 openapi/components/responses/OrderNotFound.yaml

diff --git a/openapi/components/responses/MenuItemNotFound.yaml b/openapi/components/responses/MenuItemNotFound.yaml
deleted file mode 100644
index 11ee078..0000000
--- a/openapi/components/responses/MenuItemNotFound.yaml
+++ /dev/null
@@ -1,13 +0,0 @@
-description: Menu item not found.
-content:
-  application/problem+json:
-    schema:
-      $ref: ../schemas/Error.yaml
-    examples:
-      MenuItemNotFound:
-        summary: No menu item with this ID
-        dataValue:
-          type: about:blank
-          title: Menu item not found
-          status: 404
-          instance: /menu/prd_01h1s5z6vf2mm1mz3hevnn9va7
diff --git a/openapi/components/responses/NotFound.yaml b/openapi/components/responses/NotFound.yaml
index 71c6986..ee9387a 100644
--- a/openapi/components/responses/NotFound.yaml
+++ b/openapi/components/responses/NotFound.yaml
@@ -11,3 +11,17 @@ content:
           title: Cannot GET /.well-known/oauth-authorization-server
           status: 404
           instance: /.well-known/oauth-authorization-server
+      MenuItemNotFound:
+        summary: No menu item with this ID
+        dataValue:
+          type: about:blank
+          title: Menu item not found
+          status: 404
+          instance: /menu/prd_01h1s5z6vf2mm1mz3hevnn9va7
+      OrderNotFound:
+        summary: No order with this ID
+        dataValue:
+          type: about:blank
+          title: Order not found
+          status: 404
+          instance: /orders/ord_01h1s5z6vf2mm1mz3hevnn9va7
diff --git a/openapi/components/responses/OAuth2BadRequest.yaml b/openapi/components/responses/OAuth2BadRequest.yaml
index cae087a..2655ad9 100644
--- a/openapi/components/responses/OAuth2BadRequest.yaml
+++ b/openapi/components/responses/OAuth2BadRequest.yaml
@@ -5,3 +5,14 @@ content:
   application/json:
     schema:
       $ref: ../schemas/OAuthError.yaml
+    examples:
+      InvalidGrant:
+        summary: Refresh token is invalid or expired
+        dataValue:
+          error: invalid_grant
+          error_description: Invalid refresh token
+      InvalidClientMetadata:
+        summary: Requested scope does not exist
+        dataValue:
+          error: invalid_client_metadata
+          error_description: "scopes: Invalid enum value. Expected 'menu:read' | 'menu:write' | 'orders:read' | 'orders:write' | 'revenue:read', received 'admin'"
diff --git a/openapi/components/responses/OAuth2RegistrationBadRequest.yaml b/openapi/components/responses/OAuth2RegistrationBadRequest.yaml
deleted file mode 100644
index f43c773..0000000
--- a/openapi/components/responses/OAuth2RegistrationBadRequest.yaml
+++ /dev/null
@@ -1,11 +0,0 @@
-description: Invalid client metadata (RFC 7591 Section 3.2.2).
-content:
-  application/json:
-    schema:
-      $ref: ../schemas/OAuthError.yaml
-    examples:
-      InvalidClientMetadata:
-        summary: Requested scope does not exist
-        dataValue:
-          error: invalid_client_metadata
-          error_description: "scopes: Invalid enum value. Expected 'menu:read' | 'menu:write' | 'orders:read' | 'orders:write' | 'revenue:read', received 'admin'"
diff --git a/openapi/components/responses/OAuth2RegistrationUnauthorized.yaml b/openapi/components/responses/OAuth2RegistrationUnauthorized.yaml
deleted file mode 100644
index e77fdf8..0000000
--- a/openapi/components/responses/OAuth2RegistrationUnauthorized.yaml
+++ /dev/null
@@ -1,16 +0,0 @@
-description: The registration access token is missing or invalid (RFC 7592 Section 2.1).
-headers:
-  WWW-Authenticate:
-    description: 'Authentication challenge, for example: `Bearer realm="redocly-cafe", error="invalid_token"`.'
-    schema:
-      type: string
-content:
-  application/json:
-    schema:
-      $ref: ../schemas/OAuthError.yaml
-    examples:
-      InvalidToken:
-        summary: Wrong registration access token
-        dataValue:
-          error: invalid_token
-          error_description: Invalid registration access token
diff --git a/openapi/components/responses/OAuth2Unauthorized.yaml b/openapi/components/responses/OAuth2Unauthorized.yaml
index 79f935f..c6e9d02 100644
--- a/openapi/components/responses/OAuth2Unauthorized.yaml
+++ b/openapi/components/responses/OAuth2Unauthorized.yaml
@@ -1,9 +1,9 @@
 description: |
-  Client authentication failed (`error: invalid_client`, RFC 6749 Section 5.2).
-  When the client used HTTP Basic, the response carries a `WWW-Authenticate: Basic` challenge.
+  Client authentication failed (`error: invalid_client`, RFC 6749 Section 5.2) or the presented bearer token is invalid (`error: invalid_token`, RFC 6750).
+  The response carries a `WWW-Authenticate` challenge naming the expected authentication scheme.
 headers:
   WWW-Authenticate:
-    description: 'Authentication challenge, for example: `Basic realm="redocly-cafe"`.'
+    description: 'Authentication challenge, for example: `Basic realm="redocly-cafe"` or `Bearer realm="redocly-cafe", error="invalid_token"`.'
     schema:
       type: string
 content:
@@ -16,3 +16,8 @@ content:
         dataValue:
           error: invalid_client
           error_description: Invalid client credentials
+      InvalidToken:
+        summary: Wrong registration access token
+        dataValue:
+          error: invalid_token
+          error_description: Invalid registration access token
diff --git a/openapi/components/responses/OrderNotFound.yaml b/openapi/components/responses/OrderNotFound.yaml
deleted file mode 100644
index 4cfbcd1..0000000
--- a/openapi/components/responses/OrderNotFound.yaml
+++ /dev/null
@@ -1,13 +0,0 @@
-description: Order not found.
-content:
-  application/problem+json:
-    schema:
-      $ref: ../schemas/Error.yaml
-    examples:
-      OrderNotFound:
-        summary: No order with this ID
-        dataValue:
-          type: about:blank
-          title: Order not found
-          status: 404
-          instance: /orders/ord_01h1s5z6vf2mm1mz3hevnn9va7
diff --git a/openapi/paths/menu-item-images_{menuItemId}.yaml b/openapi/paths/menu-item-images_{menuItemId}.yaml
index 4b04de2..ea959d0 100644
--- a/openapi/paths/menu-item-images_{menuItemId}.yaml
+++ b/openapi/paths/menu-item-images_{menuItemId}.yaml
@@ -22,6 +22,6 @@ get:
             description: Alternative image text.
             type: string
     '404':
-      $ref: ../components/responses/MenuItemNotFound.yaml
+      $ref: ../components/responses/NotFound.yaml
     '500':
       $ref: ../components/responses/InternalServerError.yaml
diff --git a/openapi/paths/menu_{menuItemId}.yaml b/openapi/paths/menu_{menuItemId}.yaml
index 634c258..d7caa01 100644
--- a/openapi/paths/menu_{menuItemId}.yaml
+++ b/openapi/paths/menu_{menuItemId}.yaml
@@ -19,6 +19,6 @@ delete:
     '403':
       $ref: ../components/responses/Forbidden.yaml
     '404':
-      $ref: ../components/responses/MenuItemNotFound.yaml
+      $ref: ../components/responses/NotFound.yaml
     '500':
       $ref: ../components/responses/InternalServerError.yaml
diff --git a/openapi/paths/oauth2_register.yaml b/openapi/paths/oauth2_register.yaml
index ac8b828..a036ad5 100644
--- a/openapi/paths/oauth2_register.yaml
+++ b/openapi/paths/oauth2_register.yaml
@@ -64,6 +64,6 @@ post:
           schema:
             $ref: ../components/schemas/OAuth2Client.yaml
     '400':
-      $ref: ../components/responses/OAuth2RegistrationBadRequest.yaml
+      $ref: ../components/responses/OAuth2BadRequest.yaml
     '500':
       $ref: ../components/responses/OAuth2ServerError.yaml
diff --git a/openapi/paths/oauth2_register_{clientId}.yaml b/openapi/paths/oauth2_register_{clientId}.yaml
index ef7fd05..21474e3 100644
--- a/openapi/paths/oauth2_register_{clientId}.yaml
+++ b/openapi/paths/oauth2_register_{clientId}.yaml
@@ -19,7 +19,7 @@ get:
           schema:
             $ref: ../components/schemas/OAuth2Client.yaml
     '401':
-      $ref: ../components/responses/OAuth2RegistrationUnauthorized.yaml
+      $ref: ../components/responses/OAuth2Unauthorized.yaml
     '500':
       $ref: ../components/responses/OAuth2ServerError.yaml
 put:
@@ -62,9 +62,9 @@ put:
           schema:
             $ref: ../components/schemas/OAuth2Client.yaml
     '400':
-      $ref: ../components/responses/OAuth2RegistrationBadRequest.yaml
+      $ref: ../components/responses/OAuth2BadRequest.yaml
     '401':
-      $ref: ../components/responses/OAuth2RegistrationUnauthorized.yaml
+      $ref: ../components/responses/OAuth2Unauthorized.yaml
     '500':
       $ref: ../components/responses/OAuth2ServerError.yaml
 delete:
@@ -82,6 +82,6 @@ delete:
     '204':
       description: Client registration deleted.
     '401':
-      $ref: ../components/responses/OAuth2RegistrationUnauthorized.yaml
+      $ref: ../components/responses/OAuth2Unauthorized.yaml
     '500':
       $ref: ../components/responses/OAuth2ServerError.yaml
diff --git a/openapi/paths/oauth2_revoke.yaml b/openapi/paths/oauth2_revoke.yaml
index 5c935e2..0283fc1 100644
--- a/openapi/paths/oauth2_revoke.yaml
+++ b/openapi/paths/oauth2_revoke.yaml
@@ -25,28 +25,20 @@ post:
             token:
               type: string
               description: The access or refresh token to revoke.
-              examples:
-                - YOUR_ACCESS_TOKEN
             token_type_hint:
               type: string
               enum:
                 - access_token
                 - refresh_token
               description: Optional hint about the token type.
-              examples:
-                - access_token
             client_id:
               type: string
               description: Client identifier.
                 Omit when authenticating with HTTP Basic.
-              examples:
-                - client_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
             client_secret:
               type: string
               description: Client secret.
                 Omit when authenticating with HTTP Basic.
-              examples:
-                - YOUR_CLIENT_SECRET
           required:
             - token
         examples:
diff --git a/openapi/paths/oauth2_token.yaml b/openapi/paths/oauth2_token.yaml
index 574b808..64e0682 100644
--- a/openapi/paths/oauth2_token.yaml
+++ b/openapi/paths/oauth2_token.yaml
@@ -41,52 +41,36 @@ post:
                 - client_credentials
                 - refresh_token
               description: The OAuth2 grant type.
-              examples:
-                - client_credentials
             client_id:
               type: string
               description: Client identifier.
                 Omit when authenticating with HTTP Basic.
-              examples:
-                - client_fa18ff130e1a8f445509f7e5d1d97880
             client_secret:
               type: string
               description: Client secret.
                 Omit when authenticating with HTTP Basic.
-              examples:
-                - YOUR_CLIENT_SECRET
             code:
               type: string
               description: The authorization code (required for `authorization_code`).
-              examples:
-                - AUTHORIZATION_CODE
             redirect_uri:
               type: string
               format: uri
               description: Must match the redirect URI used in the authorization request.
                 Required for `authorization_code`).
-              examples:
-                - https://api.cafe.redocly.com/callback
             code_verifier:
               type: string
               minLength: 43
               maxLength: 128
               description: PKCE code verifier (RFC 7636)
                 Required when the authorization request included a `code_challenge`.
-              examples:
-                - dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
             refresh_token:
               type: string
               description: The refresh token.
                 Required for `refresh_token`.
-              examples:
-                - YOUR_REFRESH_TOKEN
             scope:
               type: string
               description: Space-separated scopes to request.
                 Defaults to the previously granted or registered scopes.
-              examples:
-                - menu:read orders:read
           required:
             - grant_type
         examples:
diff --git a/openapi/paths/order-items.yaml b/openapi/paths/order-items.yaml
index eadbcf5..d5b7de8 100644
--- a/openapi/paths/order-items.yaml
+++ b/openapi/paths/order-items.yaml
@@ -28,6 +28,6 @@ get:
     '403':
       $ref: ../components/responses/Forbidden.yaml
     '404':
-      $ref: ../components/responses/OrderNotFound.yaml
+      $ref: ../components/responses/NotFound.yaml
     '500':
       $ref: ../components/responses/InternalServerError.yaml
diff --git a/openapi/paths/orders_{orderId}.yaml b/openapi/paths/orders_{orderId}.yaml
index d1dad5b..48109bf 100644
--- a/openapi/paths/orders_{orderId}.yaml
+++ b/openapi/paths/orders_{orderId}.yaml
@@ -38,7 +38,7 @@ get:
     '403':
       $ref: ../components/responses/Forbidden.yaml
     '404':
-      $ref: ../components/responses/OrderNotFound.yaml
+      $ref: ../components/responses/NotFound.yaml
     '500':
       $ref: ../components/responses/InternalServerError.yaml
 patch:
@@ -95,7 +95,7 @@ patch:
     '403':
       $ref: ../components/responses/Forbidden.yaml
     '404':
-      $ref: ../components/responses/OrderNotFound.yaml
+      $ref: ../components/responses/NotFound.yaml
     '500':
       $ref: ../components/responses/InternalServerError.yaml
 delete:
@@ -121,6 +121,6 @@ delete:
     '403':
       $ref: ../components/responses/Forbidden.yaml
     '404':
-      $ref: ../components/responses/OrderNotFound.yaml
+      $ref: ../components/responses/NotFound.yaml
     '500':
       $ref: ../components/responses/InternalServerError.yaml

From 61c532822dd3b17ba287497964cfb8b2b5dea1d3 Mon Sep 17 00:00:00 2001
From: Vadym Vasylyshyn <51933329+vadyvas@users.noreply.github.com>
Date: Mon, 19 Oct 2026 18:05:35 +0300
Subject: [PATCH 7/7] chore: fix rule order

---
 redocly.yaml | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/redocly.yaml b/redocly.yaml
index 6b7b7f3..6247e06 100644
--- a/redocly.yaml
+++ b/redocly.yaml
@@ -8,6 +8,17 @@ rules:
   operation-tag-defined: error
   no-invalid-schema-examples: error
   no-invalid-media-type-examples: error
+  rule/operation-summary:
+    subject:
+      type: Operation
+      property: summary
+    where:
+      - subject:
+          type: Paths
+        assertions:
+          defined: true
+    assertions:
+      pattern: /^(Create|Get|Retrieve|Replace|Update|Delete|Login|Send|Callback|Cancel|List|Partially update|Revoke).*[^\.]$/
   rule/operation-summary-sentence-case:
     subject:
       type: Operation
@@ -22,17 +33,6 @@ rules:
     message: Example summary must be sentence cased.
     assertions:
       pattern: /^([A-Z]{2,}|[A-Z][^A-Z]*|OAuth2)(?=\s|$)(\s+\(?(?:[A-Z]{2,}|[^A-Z]*|OAuth2)\)?(?=\s|$))*$/
-  rule/operation-summary:
-    subject:
-      type: Operation
-      property: summary
-    where:
-      - subject:
-          type: Paths
-        assertions:
-          defined: true
-    assertions:
-      pattern: /^(Create|Get|Retrieve|Replace|Update|Delete|Login|Send|Callback|Cancel|List|Partially update|Revoke).*[^\.]$/
 
 logo:
   srcSet: "./images/cafe-logo-black.svg light, ./images/cafe-logo-white.svg dark"