​
Add an OpenAPI File

To document your API endpoints, you’ll need a valid OpenAPI file in either JSON or YAML format. This file needs to follow the OpenAPI 3.0+ specification.

​
Quick Setup: Auto-generate API Pages

The easiest way to get started is to add an openapi field to your mint.json file. You can either:

  • Point to an OpenAPI file in your docs folder
  • Link to an OpenAPI file hosted online

Mintlify will then create pages for each API endpoint automatically.

Setting up with Anchors:

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

Setting up with Tabs:

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

Check if your OpenAPI file is valid with this command:
mintlify openapi-check <yourFile>

When you use this auto-generate option, your pages will have these default settings:

  • The page title will use the OpenAPI operation’s summary field, or create one from the endpoint details
  • The description will come from the OpenAPI operation’s description field
  • The version will match what’s in your anchor or tab settings

Need more control? You can create custom pages for each API endpoint using MDX files.

​
Custom API Pages with MDX

Sometimes you might want to:

  • Change how the page information appears
  • Add extra content
  • Skip certain API endpoints
  • Change the order of pages

In these cases, you’ll need to create MDX files for your API endpoints. Here’s an example from Elevenlabs.

​
Create MDX Files Automatically

If you have many API endpoints, creating MDX files by hand can take a long time. Our Mintlify scraper tool can create these files for you:

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>

Want to save the files in a specific folder? Use the -o option:

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference

Your OpenAPI file must be valid for this to work.

​
Create MDX Files by Hand

You can also create MDX pages manually. Just add an openapi field in the page’s settings to link it to your API endpoint.

This will automatically add the endpoint’s details and an interactive API playground to your page.

If you have multiple OpenAPI files, include the file path to help Mintlify find the right one:


Make sure the method and path match exactly what’s in your OpenAPI file.

​
Pages for API Data Types

You can also create pages that explain the data types (schemas) defined in your OpenAPI file: