Skip to main content
OpenAPI is a specification for describing APIs. Mintlify supports OpenAPI 3.0 and 3.1 documents to generate interactive API documentation and keep it up to date.

​
Add an OpenAPI specification file

To document your endpoints with OpenAPI, you need one or more valid OpenAPI specifications in either JSON or YAML format that follow the OpenAPI specification 3.0 or 3.1. Add OpenAPI specifications to your documentation repository or host them online where you can access the specifications by URL. Specifications stored in your repository are served as downloadable files at their path on your docs domain.
Mintlify supports $ref for internal references only within a single OpenAPI document. External references are not supported.

​
Describe your API

We recommend the following resources to learn about and construct your OpenAPI specification:

​
Specify the base URL for your API

To enable the API playground, add a servers field to your OpenAPI specification with your API’s base URL. 
{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}
In an OpenAPI specification, different API endpoints are specified by their paths, like /users/{id} or simply /. The base URL defines where these paths should be appended. The API playground uses these server URLs to determine where to send requests. If you specify multiple servers, a dropdown allows users to toggle between servers.
If your API has endpoints that exist at different URLs, you can override the servers field for a given path or operation.

​
Specify authentication

To enable authentication in your API documentation and playground, configure the securitySchemes and security fields in your OpenAPI specification.
1

Define your authentication method

Add a securitySchemes field to define how users authenticate.This example shows a configuration for bearer authentication.
{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
2

Apply authentication to your endpoints

Add a security field to require authentication.
{
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
Common authentication types include:
  • API Keys: For header, query, or cookie-based keys
  • Bearer: For JWT or OAuth tokens
  • Basic: For username and password
If different endpoints require different authentication methods, you can override the security field per operation.

​
Customize your endpoint pages

Customize your endpoint pages by adding the x-mint extension to your OpenAPI specification. The x-mint extension provides additional control over how your API documentation is generated and displayed.

​
Metadata

Override the default metadata for generated API pages by adding x-mint: metadata to any operation. You can use any metadata field that would be valid in MDX frontmatter except for openapi. 
{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "description": "Retrieve a list of users",
        "x-mint": {
          "metadata": {
            "title": "List all users",
            "description": "Fetch paginated user data with filtering options",
            "og:title": "Display a list of users"
          }
        }
      }
    }
  }
}
You can also control playground display per endpoint using the playground and groups metadata fields: 
{
  "paths": {
    "/admin/users": {
      "post": {
        "summary": "Create admin user",
        "x-mint": {
          "metadata": {
            "playground": "auth",
            "groups": ["admin"],
            "public": true
          }
        }
      }
    }
  }
}
This configuration makes the page publicly visible while restricting the interactive playground to authenticated users in the admin group.

​
Content

Add content before the auto-generated API documentation using x-mint: content. The x-mint: content extension supports all Mintlify MDX components and formatting. 
{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create user",
        "x-mint": {
          "content": "## Prerequisites\n\nThis endpoint requires admin privileges and has rate limiting.\n\n<Note>User emails must be unique across the system.</Note>"
        }
      }
    }
  }
}

​
Href

Set the URL of the autogenerated endpoint page using x-mint: href. When x-mint: href is present, the generated API page uses the specified URL instead of the default autogenerated URL. 
{
  "paths": {
    "/legacy-endpoint": {
      "get": {
        "summary": "Legacy endpoint",
        "x-mint": {
          "href": "/deprecated-endpoints/legacy-endpoint"
        }
      }
    }
  }
}

​
Auto-populate API pages

Add an openapi field to any navigation element in your docs.json to automatically generate pages for OpenAPI endpoints. The openapi field accepts either a file path in your docs repo or a URL to a hosted OpenAPI document.
To exclude specific endpoints from your auto-generated API pages, add the x-hidden property to the operation in your OpenAPI spec.
There are two approaches for adding endpoint pages into your documentation:

​
Dedicated API sections

Generate dedicated API sections by adding an openapi field to a navigation element. All endpoints in the specification are included. 
"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "openapi": "openapi.json"
    }
  ]
}
To organize multiple OpenAPI specifications in separate sections, assign each specification to a different group: 
"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Users API",
          "openapi": {
            "source": "/path/to/users-openapi.json",
            "directory": "users-api-reference"
          }
        },
        {
          "group": "Admin API",
          "openapi": {
            "source": "/path/to/admin-openapi.json",
            "directory": "admin-api-reference"
          }
        }
      ]
    }
  ]
}
The directory field is optional and specifies where generated API pages are stored in your docs repo. If not specified, defaults to the api-reference directory.

​
Selective endpoints

When you want more control over where endpoints appear in your documentation, you can reference specific endpoints in your navigation.

​
Set a default OpenAPI spec

Configure a default OpenAPI specification for a navigation element, then reference specific endpoints in the pages field: 
"navigation": {
  "tabs": [
    {
      "tab": "Getting started",
      "pages": [
        "quickstart",
        "installation"
      ]
    },
    {
      "tab": "API reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "api-overview",
        "GET /users",
        "POST /users",
        "guides/authentication"
      ]
    }
  ]
}
Any page entry matching the format METHOD /path generates an API page for that endpoint using the default OpenAPI specification.

​
OpenAPI spec inheritance

OpenAPI specifications are inherited down the navigation hierarchy. Child navigation elements inherit their parent’s OpenAPI specification unless they define their own. 
{
  "group": "API reference",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "overview",
    "authentication",
    "GET /users",
    "POST /users",
    {
      "group": "Orders",
      "openapi": "/path/to/openapi-v2.json",
      "pages": [
        "GET /orders",
        "POST /orders"
      ]
    }
  ]
}

​
Create MDX pages from your OpenAPI specification

For more granular control over individual endpoint pages, create MDX pages from your OpenAPI specification. This lets you customize page metadata, content, and reorder or exclude pages in your navigation.

​
Document endpoints

Create a page for each endpoint and specify which OpenAPI operation to display using the openapi field in the frontmatter. 
---
title: "Get users"
description: "Returns all plants from the system that the user has access to"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---
The method and path must exactly match your OpenAPI spec.

​
Autogenerate endpoint pages

To autogenerate MDX files from your OpenAPI specification, use the Mintlify scraper: 
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o <folder-name>
Add the -o flag to specify a folder to populate the files into. If a folder is not specified, the files populate in the working directory.

​
Document data models

Create a page for each data structure defined in your OpenAPI specification’s components.schemas using the openapi-schema field in the frontmatter. 
---
openapi-schema: OrderItem
---
If you have schemas with the same name in multiple files, specify the OpenAPI file.

​
Webhooks

Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. Webhooks are supported in OpenAPI 3.1+ documents. Add a webhooks field to your OpenAPI document alongside the paths field. To create an MDX page for a webhook (OpenAPI 3.1+), use webhook instead of an HTTP method: 
---
title: "Order updated webhook"
description: "Triggered when an order is updated"
openapi: "openapi.json webhook orderUpdated"
---
The webhook name must exactly match the key in your OpenAPI spec’s webhooks field.

Build docs developers (and LLMs) love

Get started for freeTalk to us