OpenAPI Setup

Reference OpenAPI endpoints in your docs pages

Add Your OpenAPI Specification

Start with a valid OpenAPI document (version 3.0+) in JSON or YAML format that follows the OpenAPI specification.

Auto-populate API Pages

Add an openapi field to a tab or anchor in your mint.json. This can be either a path to a local OpenAPI document or a URL to a hosted one.

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

Mintlify will automatically generate pages for each OpenAPI operation with default metadata from your specification.

Custom API Pages

For more control over your API documentation, you can create individual MDX pages for each operation:

1. Auto-generate MDX files using our scraper:

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

2. Manually create MDX files with OpenAPI references:

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

OpenAPI Schemas

Create pages for individual schemas defined in your OpenAPI document:

---
openapi-schema: SchemaName
---