From e50d603041e8d416da233b2ed1f1d56e046c67ed Mon Sep 17 00:00:00 2001 From: dino475 Date: Wed, 5 Mar 2025 21:14:49 -0800 Subject: [PATCH 1/2] quick fix to improve the OpenAPI pages --- api-playground/openapi/setup.mdx | 2 ++ api-playground/troubleshooting.mdx | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 93b47c02d..b3a35dae6 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -49,6 +49,8 @@ The fastest way to get started with OpenAPI is to add an `openapi` field to a ta } ``` +The directory field is optional. If not specified, the files will be placed in the **api-reference** folder of the docs repo. + When using this option, the metadata for the generated pages will have the following default values: * `title`: The `summary` field from the OpenAPI operation, if present. Otherwise a title generated from the HTTP method and endpoint. diff --git a/api-playground/troubleshooting.mdx b/api-playground/troubleshooting.mdx index 4b411e6a1..f638c202e 100644 --- a/api-playground/troubleshooting.mdx +++ b/api-playground/troubleshooting.mdx @@ -16,7 +16,7 @@ Here's a list of common issues we've seen customers run into: To verify your OpenAPI document will pass validation: - 1. Visit [this validator](https://apitools.dev/swagger-parser/online/) + 1. Visit [this validator](https://editor.swagger.io/) 2. Switch to the "Validate text" tab 3. Paste in your OpenAPI document 4. Click "Validate it!" From 8a1976e554903222e239e5bd9a625b27d98271b2 Mon Sep 17 00:00:00 2001 From: dino475 Date: Thu, 6 Mar 2025 09:42:27 -0800 Subject: [PATCH 2/2] clarrified that the URL for the OAS can be added to the docs.json --- api-playground/openapi/setup.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index b3a35dae6..ff34e940c 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -79,6 +79,8 @@ and the API playground will be automatically generated from the OpenAPI document If you have multiple OpenAPI files, include the path to the OpenAPI file to ensure Mintlify finds the correct OpenAPI document. This is not required if you have only one OpenAPI file - it will automatically detect your OpenAPI file. +If you want to reference an external OpenAPI file using this method, provide the file’s URL in the docs.json. See [here](https://mintlify.com/docs/settings/global#param-source-4) for the correct format. + ```md Example --- @@ -95,8 +97,6 @@ only one OpenAPI file - it will automatically detect your OpenAPI file. ``` -
- In most cases, the method and path must match the method and path specified in the OpenAPI document exactly. If the endpoint doesn't exist in the OpenAPI