feat(openapi): make the description pass the reunite starter rules

Author: vadyvas

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/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

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

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

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

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

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