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:

In the repo

The most common method of setting up OpenAPI with Mintlify is to add your OpenAPI documents directly to your docs repo. You’ll then add the paths to each OpenAPI document to the openapi field in your mint.json:

mint.json
{
  ...
  "openapi": ["/openapi.yml"],
  ...
}

That’s it! Any endpoints in this OpenAPI document can now be referenced in your MDX files.

On the web

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 by setting the openapi field in your mint.json to the document URL. Here’s an example:

mint.json
{
  ...
  "openapi": "https://mintlify.com/specs/v2/openapi.json",
  ...
}

Notice that the openapi field is a string, not an array. Arrays containing OpenAPI document URLs are not yet supported in Mintlify.

You can then reference endpoints in this OpenAPI document just as you would with documents stored in the repository.

Create MDX files for OpenAPI endpoints

To add the OpenAPI endpoints into your docs, each endpoint requires a corresponding MDX file. You can autogenerate these MDX files from your OpenAPI document using our scraper, or create each page manually.

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.

If your OpenAPI document is invalid, the files will not autogenerate.

Manually generate files

---
title: "Get users"
openapi: "GET /users"
---

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.

---
title: "Get users"
openapi: "openapi-1 GET /users"
---

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.

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:

---
openapi-schema: OrderItem
---