OpenAPI Setup

Reference OpenAPI endpoints in your docs pages

Getting Started with OpenAPI Integration

Prerequisites

Before integrating OpenAPI into your documentation, ensure you have:

• A valid OpenAPI document (JSON or YAML format)
• OpenAPI specification 3.0 or higher
• Mintlify CLI installed

Validate your OpenAPI specification using our CLI:

mintlify openapi-check <openapiFilenameOrUrl>

Implementation Methods

Method 1: Auto-population with Navigation Tabs

The quickest way to implement OpenAPI is through your docs.json configuration. You can either reference a local file or a hosted URL.

Tab-Based Navigation

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

Auto-generated pages will use the following metadata by default:

• Title: OpenAPI operation summary or generated from HTTP method/endpoint
• Description: OpenAPI operation description
• Version: Version value from the anchor/tab (if present)

Method 2: Custom MDX Pages

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

1

Create an MDX File

Create a new MDX file for your API endpoint. Here’s an example structure:

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

2

Specify OpenAPI Reference

The openapi field format should follow:

openapi: <file-path> <method> <path>

If you only have one OpenAPI file, the file path is optional - Mintlify will automatically detect it.

3

Add Custom Content

Add any additional content or customization below the frontmatter.

The method and path must exactly match those in your OpenAPI document. For webhooks, use “webhook” instead of the HTTP method (e.g., “POST”).

Method 3: Automated File Generation

For large OpenAPI documents, use our scraping tool to automatically generate MDX files.

1

Install the Scraper

Use our @mintlify/scraping package:

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

2

Specify Output Directory

Add the -o flag to choose where files are generated:

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

3

Update Navigation

Add the generated navigation entries to your configuration:

• Append them to existing navigation, or
• Manually organize them in your preferred structure

The scraper requires a valid OpenAPI document. Invalid specifications will not generate files.

Working with OpenAPI Schemas

Individual Schema Pages

Create dedicated pages for schemas defined in your OpenAPI document’s components.schemas:

Example

---
openapi-schema: OrderItem
---

Schema pages automatically inherit documentation from your OpenAPI specification while allowing you to add custom content and examples.