Writing OpenAPI
Learn how to use OpenAPI features to make your Mintlify docs better
Getting Started with OpenAPI
Want to learn how to write OpenAPI documents? Here are the best tools to help you get started:
- Swagger’s OpenAPI Guide - Learn the basics of OpenAPI
- OpenAPI v3.1.0 Specification - Full details about the latest version
- Swagger & OpenAPI Validator - Check your OpenAPI document for errors
- Swagger’s Editor - See working examples in action
Most of Swagger’s OpenAPI Guide covers version 3.0, but it works for v3.1 too. Want to know what changed between versions? Check out OpenAPI’s blog post.
Setting Up Your API’s Web Address
Every API has a base web address (URL) where it lives. In OpenAPI, you set this using the servers field. You’ll need this for features like the API Playground to work. Learn how to set up your server URL by reading the Swagger documentation.
When you use the API Playground, it will use these server URLs to send requests. If you list multiple servers, you’ll see a dropdown menu to switch between them. Without a server URL, the API Playground will only work in simple mode and won’t send real requests.
Does your API use different web addresses for different features? No problem! You can set different server URLs for specific parts of your API.
Setting Up Security
Most APIs need users to prove who they are before they can use them. This is called authentication. OpenAPI lets you set this up using the securitySchemes field. It supports common security methods like:
- Basic Authentication (username and password)
- Bearer Authentication (using tokens)
- API Keys
To use these security methods in your API, you’ll need the security field. Since this can be tricky to set up, check out Swagger’s guide to authentication for help and examples.
The API Playground will automatically add the right security fields based on your OpenAPI settings.
Need different security for different parts of your API? You can set different security requirements for specific operations.