Writing OpenAPI

Use OpenAPI features to enhance your Mintlify docs

Describing your API

There are many great tools online for learning about and constructing OpenAPI documents. Here are our favorites:

• Swagger’s OpenAPI Guide for familiarizing yourself with the OpenAPI syntax
• OpenAPI v3.1.0 Specification for all the details about the newest OpenAPI specification
• Swagger & OpenAPI Validator for debugging your OpenAPI document
• Swagger’s Editor for seeing examples in action

Swagger’s OpenAPI Guide is for OpenAPI v3.0, but nearly all of the information is applicable to v3.1. For more information on the differences between v3.0 and v3.1, check out OpenAPI’s blog post.

Specifying the URL for your API

In an OpenAPI document, different API endpoints are specified by their paths, like /users/{id}, or maybe simply /. To specify the base URL to which these paths should be appended, OpenAPI provides the servers field. This field is necessary to use some Mintlify features like the API Playground. Read how to configure the servers field in the Swagger documentation.

The API Playground will use these server URLs to determine where to send requests. If multiple servers are specified, a dropdown will appear to allow toggling between servers. If no server is supplied, the API Playground will use simple mode, as there is no way to send a request.

If different endpoints within your API exist at different URLs, you can override the server field for a given path or operation.

Specifying authentication

Nearly all APIs require some method of authentication. OpenAPI provides the securitySchemes field for defining the methods of authentication used throughout your API, with simple configuration for the most common authentication types - Basic, Bearer, and API Keys. To apply these authentication methods to your endpoints, OpenAPI uses the security field. The syntax for defining and applying authentication is a bit unintuitive, so definitely check out Swagger’s documentation and examples on the topic.

The API descriptions and API Playground will add authentication fields based on the security configurations in your OpenAPI document.

If different endpoints within your API require different methods of authentication, you can override the security field for a given operation.