Writing OpenAPI

Use OpenAPI features to enhance your Mintlify docs

Getting Started with OpenAPI

To get started with OpenAPI, we recommend using Swagger’s OpenAPI Guide to learn the basics and Swagger’s Editor to write your specifications.

We support OpenAPI v3.1. For differences between v3.0 and v3.1, see OpenAPI’s migration guide.

Essential Components

Base URL Configuration

• Use the servers field to specify your API’s base URL
• Multiple servers can be defined for different environments
• Required for using Mintlify’s API Playground features

Authentication Setup

• Define authentication methods using securitySchemes
• Common types include Basic, Bearer, and API Keys
• Apply authentication using the security field
• Can be configured globally or per-endpoint

For detailed OpenAPI syntax and examples, refer to the OpenAPI v3.1.0 Specification.