> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-dean-clarifying-localization.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI Setup

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

## Auto-populate API pages

The fastest way to get started with OpenAPI is to add an `openapi` field to a tab or anchor in the `mint.json`. This field can contain either the path to an OpenAPI document in your docs repo, or the URL of a hosted OpenAPI document. Mintlify will automatically generate a page for each OpenAPI operation and place them in the tab/anchor.

**Example with Anchors:**

```json {5}
{
  "anchors": [
    {
      "name": "API Reference",
      "openapi": "/path/to/openapi.json",
      "url": "api-reference",
      "icon": "square-terminal"
    }
  ]
}
```

![](https://mintlify.s3.us-west-1.amazonaws.com/mintlify-dean-clarifying-localization/images/anchors-autogeneration-anchors.png)

**Example with Tabs:**

```json {6}
{
  "tabs": [
    {
      "name": "API Reference",
      "url": "api-reference",
      "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}
```

![](https://mintlify.s3.us-west-1.amazonaws.com/mintlify-dean-clarifying-localization/images/autogeneration-with-tabs.png)

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.

* `description`: The `description` field from the OpenAPI operation, if present.

* `version`: The `version` value from the anchor or tab, if present.

There are some scenarios in which the default behavior isn't sufficient. If you need more customizability, you can create an MDX page for your OpenAPI operation, and modify it just like any other MDX page.

## Create MDX files for API pages

If you want to customize the page metadata, add additional content, omit certain OpenAPI operations, or reorder OpenAPI pages in your navigation, you'll need an MDX page for each operation. Here is [an example MDX OpenAPI page](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). 

![](https://mintlify.s3.us-west-1.amazonaws.com/mintlify-dean-clarifying-localization/images/elevenlabs-mdx-autogeneration-example.png)

### Autogenerate files

For large OpenAPI documents, creating one MDX page for each OpenAPI operation can be a lot of work. To make it easier, we created a local OpenAPI page scraper.

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.

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

```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).

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.
</Note>

### Manually specify files

You can always create an MDX page manually, and reference the OpenAPI operation in the page's metadata using the `openapi` field.

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

By using the OpenAPI reference, the name, description, parameters, responses,
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.

<CodeGroup>
  ```md Example
  ---
  title: "Get users"
  openapi: "/path/to/openapi-1.json GET /users"
  ---
  ```

  ```md Format
  ---
  title: "title of the page"
  openapi: openapi-file-path method path
  ---
  ```
</CodeGroup>

<br />

<Note>
  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 file,
  the page will be empty.
</Note>

## 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:

<CodeGroup>
  ```md Example
  ---
  openapi-schema: OrderItem
  ---
  ```

  ```md Format
  ---
  openapi-schema: "schema-key"
  ---
  ```
</CodeGroup>