docs: add troubleshooting for api pages (mintlify#267)

* add troubleshooting for api pages

* make description more generic

* add example for filenames and fix info

* DNS provider -> reverse proxy

Author: rpmccarter

api-playground/troubleshooting.mdx

@@ -0,0 +1,74 @@
+---
+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.
+Here's a list of common issues we've seen customers run into:
+
+<AccordionGroup>
+  <Accordion title="All of my OpenAPI pages are completely blank">
+    In this scenario, it's likely that either Mintlify cannot find your OpenAPI document,
+    or your OpenAPI document is invalid.
+
+    Running `mintlify dev` locally should reveal some of these issues.
+
+    To verify your OpenAPI document will pass validation:
+
+    1. Visit [this validator](https://apitools.dev/swagger-parser/online/)
+    2. Switch to the "Validate text" tab
+    3. Paste in your OpenAPI document
+    4. Click "Validate it!"
+
+    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.
+  </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}/"
+---
+```
+
+```yaml openapi.yaml
+paths:
+  "/users/{id}":
+    get:
+      ...
+```
+
+    Notice that the path in the `openapi` field has a trailing slash, whereas the path in the OpenAPI
+    document does not.
+
+    Another common issue is a misspelled filename. If you are specifying a particular OpenAPI document
+    in the `openapi` field, ensure the filename is correct. For example, if you have two OpenAPI
+    documents `openapi/v1.json` and `openapi/v2.json`, your metadata might look like this:
+
+```md api-reference/v1/users/get-user.mdx
+---
+openapi: "v1 GET /users/{id}"
+---
+```
+  </Accordion>
+
+  <Accordion title="Requests from the API Playground don't work">
+    If you have a custom domain configured, this could be an issue with your reverse proxy. By
+    default, requests made via the API Playground start with a `POST` request to the
+    `/api/request` path on the docs site. If your reverse proxy is configured to only allow `GET`
+    requests, then all of these requests will fail. To fix this, configure your reverse proxy to
+    allow `POST` requests to the `/api/request` path.
+
+    Alternatively, if your reverse proxy prevents you from accepting `POST` requests, you can configure
+    Mintlify to send requests directly to your backend with the `api.playground.disableProxy`
+    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>

mint.json

@@ -95,7 +95,8 @@
             "api-playground/mdx/configuration",
             "api-playground/mdx/authentication"
           ]
-        }
+        },
+        "api-playground/troubleshooting"
       ]
     },
     {