Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 38 additions & 15 deletions api-playground/openapi/setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,25 @@ description: "Reference OpenAPI endpoints in your docs pages"

## Add an OpenAPI specification file

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+.
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+.

## Autogenerating the API playground

You can either [autogenerate the API playground](/settings/navigation#tabs) or create MDX files for the individual OpenAPI endpoints.
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 (json or yaml) 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:**

```json
```json {5}
{
"anchors": [
{
Expand All @@ -34,7 +40,7 @@ You can add an `openapi` field to an object in the `tabs` or `anchors` array in

**Example with Tabs:**

```json
```json {6}
{
"tabs": [
{
Expand All @@ -50,30 +56,42 @@ 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 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).
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)

If you want to autogenerate MDX files for every endpoint in your OpenAPI document you can use our scraper.
If you want to autogenerate MDX files for every endpoint in your OpenAPI
document you can use our scraper.

#### Autogenerate files

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.
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 <path-to-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 in the working directory.
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 <path-to-openapi-file> -o api-reference
```

Learn more about our scraping package [here](https://www.npmjs.com/package/@mintlify/scraping).
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 reorder and 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.

<Note>
If your OpenAPI document is invalid, the files will not autogenerate.
Expand All @@ -83,9 +101,13 @@ The scraper will output an array of [Navigation entries](/settings/global#struct

<Snippet file="api-playground/openapi.mdx" />

By using the OpenAPI reference, the name, description, parameters, responses, and the API playground will be automatically generated using the specifications.
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. This is not required if you have only one OpenAPI file - it will automatically detect your OpenAPI file.
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.

<CodeGroup>

Expand Down Expand Up @@ -113,7 +135,8 @@ openapi: openapi-file-name method endpoint

## Create MDX files for OpenAPI schemas

Mintlify also allows you to create individual pages for any OpenAPI schema 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:

<CodeGroup>

Expand Down