​
What is OpenAPI?

OpenAPI (formerly known as Swagger) is a standard way to describe your API. It’s like a blueprint that tells others how your API works, what endpoints it has, and what data it expects and returns.

​
Getting Started

Let’s break down the process of adding OpenAPI documentation into simple steps:

​
Step 1: Prepare Your OpenAPI File

First, you’ll need an OpenAPI document that describes your API. This can be either:

  • A JSON file
  • A YAML file

Your document needs to follow OpenAPI version 3.0 or higher.

Not sure if your OpenAPI file is valid? Use our checker tool:

mintlify openapi-check <your-file-name-or-url>

​
Step 2: Choose How to Add Your Documentation

You have two main options for adding OpenAPI documentation:

This is the fastest way to get started. Just add your OpenAPI file location to your docs.json:

Basic Example
{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": "https://your-api-docs.json"
      }
    ]
  }
}

This will automatically create pages for all your API endpoints!

You can use either a URL or a local file path for the openapi field.

​
Option B: Custom Pages (More Flexible)

If you want more control, you can create individual pages for each API endpoint. Here’s how:

  1. Create a new .mdx file for your endpoint
  2. Add this to the top of your file:
---
title: "Your Endpoint Name"
openapi: "GET /users"
---

Need to create many pages? Use our automatic page generator:

npx @mintlify/scraping@latest openapi-file your-openapi-file.json -o api-reference

​
Step 3: Add More Details (Optional)

Once your basic setup is working, you can:

  1. Add custom descriptions to your endpoints
  2. Include example code
  3. Add authentication details
  4. Group related endpoints together

​
Advanced Configuration

​
Organizing Your API Documentation

You can organize your endpoints into groups:

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "groups": [
          {
            "group": "User Management",
            "openapi": {
              "source": "/openapi/users.json",
              "directory": "api/users"
            }
          }
        ]
      }
    ]
  }
}

​
Creating Schema Pages

Want to document your data models? You can create pages for your OpenAPI schemas:

---
title: "User Object"
openapi-schema: User
---

The schema name must match exactly what’s in your OpenAPI file under components.schemas.

​
Troubleshooting

If your OpenAPI documentation isn’t showing up:

  1. Check that your OpenAPI file is valid
  2. Make sure the paths and methods match exactly
  3. Verify that your file paths are correct
  4. Ensure you’re using OpenAPI 3.0 or higher

Need help? Join our Discord community for support!