add troubleshooting & resolution for openapi v2 (#283)

Author: mayankshouche

api-playground/troubleshooting.mdx

@@ -1,7 +1,7 @@
 ---
-title: 'Troubleshooting'
-description: 'Common issues with API References'
-icon: 'triangle-exclamation'
+title: "Troubleshooting"
+description: "Common issues with API References"
+icon: "triangle-exclamation"
 ---
 
 API pages are complicated. As a result, there are a lot of things that can go wrong.
@@ -24,13 +24,22 @@ Here's a list of common issues we've seen customers run into:
     If the text box that appears below has a green border, your document has passed validation.
     This is the exact validation package Mintlify uses to validate OpenAPI documents, so if your document
     passes validation here, there's a great chance the problem is elsewhere.
+
+    Additionally, Mintlify does not support OpenAPI 2.0. If your document uses this version of the specification,
+    you could encounter this issue. You can convert your document at [editor.swagger.io](https://editor.swagger.io/) (under Edit > Convert to OpenAPI 3):
+
+    <Frame>
+      <img src="/images/convert-oas-3.png" />
+    </Frame>
+
   </Accordion>
 
   <Accordion title="One of my OpenAPI pages is completely blank">
     This is usually caused by a misspelled `openapi` field in the page metadata. Make sure
     the HTTP method and path match the HTTP method and path in the OpenAPI document exactly.
 
     Here's an example of how things might go wrong:
+
 ```md get-user.mdx
 ---
 openapi: "GET /users/{id}/"
@@ -40,8 +49,7 @@ openapi: "GET /users/{id}/"
 ```yaml openapi.yaml
 paths:
   "/users/{id}":
-    get:
-      ...
+    get: ...
 ```
 
     Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI
@@ -56,6 +64,7 @@ paths:
 openapi: "v1 GET /users/{id}"
 ---
 ```
+
   </Accordion>
 
   <Accordion title="Requests from the API Playground don't work">
@@ -70,5 +79,6 @@ openapi: "v1 GET /users/{id}"
     setting in the `mint.json`, as described [here](/settings/global#api-configurations). This will
     likely require you to configure CORS on your server, as these requests will now come directly
     from your users' browsers.
+
   </Accordion>
 </AccordionGroup>