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. 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 in the docs.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.

Example with Tabs:

"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}

Example with Groups:

"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Endpoints",
          "openapi": {
            "source": "/path/to/openapi-1.json",
            "directory": "api-reference"
          }
        }
      ]
    }
  ]
}

The directory field is optional. If not specified, the files will be placed in the api-reference folder of the docs repo.

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.

If you have some endpoints in your OpenAPI schema that you don’t want pages generated for automatically, you can add the x-hidden property

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 from MindsDB.

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.

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.

If you want to reference an external OpenAPI file using this method, provide the file’s URL in the docs.json. See here for the correct format.

Example

---
title: "Get users"
openapi: "/path/to/openapi-1.json GET /users"
---

In most cases, 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.

For webhooks, replace the method (i.e. “POST”) with “webhook” (case insensitive) and the correct method will be generated.

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 autogenerates MDX files for your OpenAPI endpoints.

Each generated page will correspond to an OpenAPI operation under the “paths” section of the OpenAPI schema. If your OpenAPI document is version 3.1+, the scraper will also generate pages for webhooks under the “webhooks” section of the OpenAPI schema.

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.

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 reorder and add the files to your navigation manually.

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

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:

Example

---
openapi-schema: OrderItem
---