chore: make the description pass the reunite starter rules

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

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

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

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

openapi/components/responses/NotFound.yaml

@@ -3,3 +3,25 @@ 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
+      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

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

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

openapi/components/responses/OAuth2Unauthorized.yaml

@@ -10,3 +10,14 @@ 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
+      InvalidToken:
+        summary: Wrong registration access token
+        dataValue:
+          error: invalid_token
+          error_description: Invalid registration access token

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

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

redocly.yaml

@@ -3,18 +3,36 @@ extends:
 apis:
   cafe-api:
     root: "./openapi/cafe.yaml"
-    rules:
-      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
+  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).*[^\.]$/
+  rule/operation-summary-sentence-case:
+    subject:
+      type: Operation
+      property: summary
+    message: Operation 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/example-summary-sentence-case:
+    subject:
+      type: Example
+      property: summary
+    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|$))*$/
 
 logo:
   srcSet: "./images/cafe-logo-black.svg light, ./images/cafe-logo-white.svg dark"