diff --git a/api-playground/openapi/setup.mdx b/api-playground/openapi/setup.mdx index 4e85edb53..1f88d41e1 100644 --- a/api-playground/openapi/setup.mdx +++ b/api-playground/openapi/setup.mdx @@ -7,24 +7,13 @@ description: "Reference OpenAPI endpoints in your docs pages" To describe your endpoints with OpenAPI, make sure you have a valid OpenAPI document in either JSON or YAML format that follows the [OpenAPI specification](https://swagger.io/specification/). Your document must follow OpenAPI specification 3.0+. -There are two ways to configure your docs to use your OpenAPI file: - - - - The most common method of setting up OpenAPI with Mintlify is to add your OpenAPI documents directly to your docs repo. The format will either be in `.yaml` or `.json`. - - - If you have a publicly-hosted OpenAPI document that serves as the single-source-of-truth for your API, you can use that in your docs through the document URL (ex: https://mintlify.com/specs/v2/openapi.json) - - - ## Autogenerating the API playground You can either [autogenerate the API playground](/settings/navigation#tabs) or create MDX files for the individual OpenAPI endpoints. ### Auto-populate API pages -You can add an `openapi` field to an object in the `tabs` or `anchors` array in the `mint.json`. This can either be with OpenAPI documents that are in the docs repo or hosted at a link. +You can add an `openapi` field to an object in the `tabs` or `anchors` array in the `mint.json`. This can either be with OpenAPI documents that are in the docs repo (json or yaml) or hosted at a link. **Example with Anchors:** @@ -61,22 +50,22 @@ You can add an `openapi` field to an object in the `tabs` or `anchors` array in ### Create MDX files for OpenAPI endpoints -You can also create MDX files associated with each OpenAPI endpoint if you would like to add additional context to specific pages. Check out an example from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech) below. +You can also create MDX files associated with each OpenAPI endpoint if you would like to add additional context to specific pages or have more granular control over the navigation. Here is [the code](https://github.com/elevenlabs/elevenlabs-docs/blob/e5e267c97b8d1e4c21db1dcdb8b005eb1dfed7da/api-reference/speech-to-speech.mdx?plain=1#L2) from [Elevenlabs](https://elevenlabs.io/docs/api-reference/speech-to-speech). ![](/images/elevenlabs-mdx-autogeneration-example.png) -You can autogenerate these MDX files from your OpenAPI document using our scraper, or create each page manually. +If you want to autogenerate MDX files for every endpoint in your OpenAPI document you can use our scraper. -#### Autogenerate files (Recommended) +#### Autogenerate files -Our Mintlify [scraper](/api-playground/openapi/setup#autogenerate-files-recommended) helps autogenerate MDX files for your OpenAPI endpoints. Use the relative path to the OpenAPI document in your codebase. If you're using a publicly-hosted OpenAPI document, you can just supply the URL in place of a path. +Our Mintlify [scraper](https://www.npmjs.com/package/@mintlify/scraping) autogenerates MDX files for your OpenAPI endpoints. Use the relative path to the OpenAPI document in your codebase. If you're using a publicly-hosted OpenAPI document, you can supply the URL in place of a path. ```bash npx @mintlify/scraping@latest openapi-file ``` -Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files will populate into the current folder. +Add the `-o` flag to specify a folder to populate the files into. If a folder is not specified, the files will populate in the working directory. ```bash npx @mintlify/scraping@latest openapi-file -o api-reference @@ -84,7 +73,7 @@ npx @mintlify/scraping@latest openapi-file -o api-referen Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping). -The scraper will output an array of [Navigation entries](/settings/global#structure) containing your OpenAPI MDX files. You can either append these entries to your existing Navigation, or add the files to your Navigation manually. +The scraper will output an array of [Navigation entries](/settings/global#structure) containing your OpenAPI MDX files. You can either append these entries to your existing Navigation, or reorder and add the files to your navigation manually. If your OpenAPI document is invalid, the files will not autogenerate. @@ -96,7 +85,7 @@ The scraper will output an array of [Navigation entries](/settings/global#struct By using the OpenAPI reference, the name, description, parameters, responses, and the API playground will be automatically generated using the specifications. -If you have multiple OpenAPI files, include the name of the OpenAPI file (without the file type `.json` or `.yaml`) to correctly map the information. +If you have multiple OpenAPI files, include the name of the OpenAPI file (without the file type `.json` or `.yaml`) to correctly map the information. This is not required if you have only one OpenAPI file - it will automatically detect your OpenAPI file. @@ -119,12 +108,12 @@ openapi: openapi-file-name method endpoint The method endpoint must match the endpoint specified in the OpenAPI specifications exactly. If the endpoint doesn't exist in the OpenAPI file, - an empty page will be rendered. + the page will be empty. ## Create MDX files for OpenAPI schemas -Mintlify also allows you to create individual pages for any OpenAPI schemas defined in an OpenAPI document's `components.schemas` field: +Mintlify also allows you to create individual pages for any OpenAPI schema defined in an OpenAPI document's `components.schemas` field: