OpenAPI Setup

Reference OpenAPI endpoints in your docs pages

Add an OpenAPI specification file

Ensure you have a valid OpenAPI 3.0+ document in either JSON or YAML format following the OpenAPI specification.

Auto-populate API pages

Add an openapi field to a tab or anchor in the mint.json to automatically generate API pages. The field can contain either:

• A path to an OpenAPI document in your docs repo
• A URL of a hosted OpenAPI document

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

Custom API pages

Auto-generate MDX files

For large OpenAPI documents, use our scraper to generate MDX files:

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

Manual MDX creation

Create custom MDX pages for API operations using the openapi field in the frontmatter:

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

OpenAPI Schemas

Create pages for OpenAPI schemas using:

---
openapi-schema: "schema-key"
---