OpenAPI Setup

​

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. Your document must follow OpenAPI specification 3.0+.

There are two ways to configure your docs to use your OpenAPI file:

​

Autogenerating the API playground

You can either autogenerate the API playground 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.

Example with Anchors:

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

Example with Tabs:

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

​

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

You can autogenerate these MDX files from your OpenAPI document using our scraper, or create each page manually.

​

Autogenerate files (Recommended)

Our Mintlify scraper 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.

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 into the current folder.

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

Learn more about our scraping package here.

The scraper will output an array of Navigation entries containing your OpenAPI MDX files. You can either append these entries to your existing Navigation, or add the files to your Navigation manually.

​

Manually specify files

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.

​

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: