OpenAPI Setup

Reference OpenAPI endpoints in your docs pages

Add Your OpenAPI Specification

To get started, you’ll need a valid OpenAPI document (version 3.0+) in either JSON or YAML format that follows the OpenAPI specification.

Configure Your Documentation

There are two main ways to add OpenAPI documentation:

1. Auto-generate API Pages (Recommended)

The simplest way to get started is to add an openapi field to your mint.json. This can be either:

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

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

Mintlify will automatically generate pages for each API endpoint.

2. Create Custom API Pages

For more customization, you can create individual MDX pages for your API endpoints:

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

For large APIs, you can auto-generate MDX files using our scraping tool:

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