add info on multiple responses

Author: ethanpalm

api-playground/customization/managing-page-visibility.mdx

@@ -33,7 +33,7 @@ Common use cases for `x-excluded` are:
 
 Add the `x-hidden` or `x-excluded` extension under the HTTP method in your OpenAPI specification.
 
-Here are examples of how to use each property in an OpenAPI schema document for an endpoint and a webhook path:
+Here are examples of how to use each property in an OpenAPI schema document for an endpoint and a webhook path.
 
 ```json {11, 19}
 "paths": {

api-playground/customization/multiple-responses.mdx

@@ -0,0 +1,31 @@
+---
+title: "Multiple responses"
+description: "Show response variations for the same endpoint"
+---
+
+If your API returns different responses based on input parameters, user context, or other conditions of the request, you can document multiple response examples with the `examples` property.
+
+This property can be added to any response and has the following schema.
+
+```yaml
+responses:
+  "200":
+    description: Successful response
+    content:
+      application/json:
+        schema:
+          $ref: "#/components/schemas/YourResponseSchema"
+        examples:
+          us:
+            summary: Response for United States
+            value:
+              countryCode: "US"
+              currencyCode: "USD"
+              taxRate: 0.0825
+          gb:
+            summary: Response for United Kingdom
+            value:
+              countryCode: "GB"
+              currencyCode: "GBP"
+              taxRate: 0.20
+```