Documentation edits made through Mintlify web editor

mintlify · Nov 21, 2024 · d9d86d1 · d9d86d1
1 parent f823d39
commit d9d86d1
Show file tree

Hide file tree

Showing 2 changed files with 92 additions and 6 deletions.
diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx
@@ -10,6 +10,83 @@ document in either JSON or YAML format that follows the
 [OpenAPI specification](https://swagger.io/specification/). Your document must
 follow OpenAPI specification 3.0+.
 
+## OpenAPI File Formats
+
+OpenAPI specifications can be written in either YAML or JSON format. Both formats are equally valid and contain the same information - choose the one that best fits your workflow.
+
+### YAML Format
+
+YAML is often preferred for its readability and concise syntax:
+
+```yaml
+openapi: 3.0.0
+info:
+  title: Sample API
+  version: 1.0.0
+paths:
+  /users:
+    get:
+      summary: Returns a list of users
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: integer
+                    name:
+                      type: string
+```
+
+### JSON Format
+
+JSON format is also widely used, especially when working with JavaScript tools:
+
+```json
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Sample API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/users": {
+      "get": {
+        "summary": "Returns a list of users",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "id": {
+                        "type": "integer"
+                      },
+                      "name": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ## Autogenerating the API playground
 
 You can either [autogenerate the API playground](/settings/navigation#tabs) or
@@ -151,4 +228,4 @@ openapi-schema: "schema-key"
 ---
 ```
 
-</CodeGroup>
+</CodeGroup>
diff --git a/mint.json b/mint.json
@@ -122,7 +122,8 @@
     },
     {
       "group": "Advanced",
-      "pages": [{
+      "pages": [
+        {
           "icon": "code",
           "group": "Custom Scripts",
           "pages": [
@@ -196,7 +197,10 @@
     },
     {
       "group": "SDKs",
-      "pages": ["integrations/sdks/speakeasy", "integrations/sdks/stainless"]
+      "pages": [
+        "integrations/sdks/speakeasy",
+        "integrations/sdks/stainless"
+      ]
     },
     {
       "group": "Support",
@@ -208,7 +212,10 @@
     },
     {
       "group": "Privacy",
-      "pages": ["integrations/privacy/overview", "integrations/privacy/osano"]
+      "pages": [
+        "integrations/privacy/overview",
+        "integrations/privacy/osano"
+      ]
     },
     {
       "group": "Components",
@@ -240,7 +247,9 @@
     },
     {
       "group": "Changelog",
-      "pages": ["changelog/overview"]
+      "pages": [
+        "changelog/overview"
+      ]
     }
   ],
   "footer": {
@@ -324,4 +333,4 @@
       "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8"
     }
   }
-}
+}