---
updatedAt: 2026-10-07T23:12:46.000Z
agentTools:
siteIndex: https://docs.readme.com/llms.txt
siteSearch: https://docs.readme.com/agentSearch?query=term1%20term2
projectIndex: https://docs.readme.com/main/llms.txt
projectSearch: https://docs.readme.com/main/agentSearch?query=term1%20term2
---
# OpenAPI Support
Check which OpenAPI versions and file types ReadMe accepts, and what your definition gives your API Reference.
# What Is OpenAPI (Formerly Known As Swagger)?
From [the OpenAPI Specification repository](https://github.com/OAI/OpenAPI-Specification):
> The **OpenAPI Specification (OAS)** is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org)... \[that] defines a standard, programming language-agnostic interface description for [REST APIs](https://en.wikipedia.org/wiki/Representational_state_transfer).
>
> Use cases for machine-readable API definition documents include, but are not limited to: interactive documentation; code generation for documentation, clients, and servers; and automation of test cases.
>
> The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service โ the service being described may not even be owned by the creator of its description.
The OpenAPI Specification was developed privately for several years under the name **Swagger**. Back when it was known as **Swagger 2.0**, the specification was donated to the OpenAPI Initiative and became an open standard in 2015. Version 3.0.0 was released under the name **OpenAPI Specification 3.0.0**.
You can read about the revision history [here](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#appendix-a-revision-history) and read about the differences between Swagger v2.0 and OAS v3.0 [**on our blog**](https://blog.readme.com/an-example-filled-guide-to-swagger-3-2/).
To see our most up-to-date support for the OpenAPI Specification (including our support for OAS v3.1), see [our compatibility chart](https://docs.readme.com/main/docs/openapi-compatibility-chart).
# The API Reference
The API Reference section of your docs will generate reference guides based on your API definition that include working code examples and the ability to make authenticated API requests directly within the documentation.
### Got a Postman Collection? We support that too!
In addition to [OpenAPI](https://spec.openapis.org/oas/v3.1.0.html) and [Swagger](https://swagger.io/specification/v2/), you can also import [Postman Collections](https://schema.postman.com/). Postman Collections are converted to OpenAPI using [`postman-to-openapi`](https://github.com/readmeio/postman-to-openapi) prior to any validation and rendering in ReadMe.
## Supported File Types
You can import the following file types into ReadMe (either JSON or YAML):
* [OpenAPI](https://spec.openapis.org/oas/v3.1.0.html) v3.0.x/v3.1
* [Swagger](https://swagger.io/specification/v2/) v2.0
* [Postman Collections](https://schema.postman.com/) v2.0/v2.1
* Anytime a Postman collection is imported, it's converted to OpenAPI using [`postman-to-openapi`](https://github.com/joolfe/postman-to-openapi) โ check out [their docs](https://joolfe.github.io/postman-to-openapi/) to better understand how the conversion works!
# Adding Markdown Content
You can add additional Markdown content to each individual file that is imported. These changes will remain even after you re-sync as long as you do not change the `operationId` or remove the import.
### ๏ธAdding Additional Markdown Content
If you add additional Markdown content, be aware that it will be tied to the `operationId` of that specific imported API definition. If the `operationId`, or file, is removed, your additional content will also be removed.
# SDK-Generated Code
SDK-Generated Code allows you to show `api` as an option in the Node language library to your end developers who are visiting your developer hub's API reference.
If you'd like to enable it, head to the **Appearance > API Reference**, and check the box for **Use SDK-generated code for requests**. If you'd like to disable this feature, uncheck the box.
# Default Handling
When enabled, any `default` values defined in your API spec will be used to populate your request data in the API Explorer on page load, regardless of the parameter being marked as `required`.
Required object and array parameters are always sent as `{}` or `[]` when they have no other value, regardless of this setting. When set to **Always Fill**, an optional parameter whose schema `default` is `{}` or `[]` is also sent. Empty objects that appear in a selected request example are preserved in the request.
For example, this operation will populate the petName field in the API Explorer with "Buster" even though it is not marked as `required`:
```json
{
"/pet": {
"get": {
"summary": "Find pet by Name",
"description": "Returns a single pet",
"operationId": "getPetByName",
"parameters": [
{
"name": "petName",
"in": "body",
"description": "Name of pet to return",
"required": false,
"schema": {
"type": "string",
"default": "Buster",
"example": "Apollo"
}
}
]
}
}
}
```
When disabled, `default` values will only be used to populate the form field and code sample if the parameter is marked as `required`. If the operation has an `example` value or `examples` object defined, we'll use that value as a *placeholder* in the API Explorer form, but it will not populate the code sample.
For example, using the same operation as above, the petName field in the API Explorer will contain a placeholder example value "Apollo", but the code sample will not be pre-filled:
If the parameter is not marked as `required`, then the enduser must explicitly select the `default` value from the dropdown when the field is active:
To configure the **Default Handling** setting, go to **Appearance > API Reference**.
# Raw JSON Editor
### Enterprise Only
The raw JSON editor setting is only available to enterprise customers. Contact us at [growth@readme.io](mailto:growth@readme.io) if you're interested in a demo!
For most APIs, the forms on API reference pages are the most intuitive way to enter in body parameters for API requests. In the [petstore](https://petstore.swagger.io/) example below, the following form data:
...will yield JSON that looks like this:
```json
{ "complete": false, "id": 123 }
```
However, your API users may prefer to write their request body JSON by hand. That's where enabling the **Raw JSON Editor** setting may be useful. When enabled, your users will have the ability to edit their request body via a raw JSON editor.
For endpoints that support JSON request bodies, you can click the "JSON Editor" icon below your code sample (see annotation #1 below) and a raw JSON editor will appear. It will validate your JSON input and update your code sample as you type.
To configure this setting, go to **Appearance > API Reference**.
# OpenAPI Download
You can add a download button to your API Reference pages, allowing visitors to download the complete OpenAPI definition file that backs the current endpoint or webhook. When enabled, the download button at the top of each API Reference page.
## Access Control
The download action respects your project's existing **OpenAPI Access** setting:
* **Public**: The download action is visible to all visitors.
* **Teammates Only**: The download action is only visible to project team members.
Enabling the download action does not change who can access your OpenAPI definitions. It links to the existing `/openapi/` route, which continues to enforce your project's OpenAPI Access policy.
## Configuring the Setting
To enable or disable the OpenAPI Download Action, go to **Settings > Appearance > API Reference** and toggle **Show OpenAPI download action**.
The setting is disabled by default.
# Sub pages
* [Categories, Pages, and Subpages](https://docs.readme.com/main/docs/openapi-categories-pages-subpages.md)
* [Re-syncing Your OpenAPI Document](https://docs.readme.com/main/docs/openapi-resyncing.md)
* [OpenAPI Compatibility Chart](https://docs.readme.com/main/docs/openapi-compatibility-chart.md)
* [OpenAPI Extensions](https://docs.readme.com/main/docs/openapi-extensions.md)
# Sibling pages
* [Creating a Project](https://docs.readme.com/main/docs/creating-a-project.md)
* [Navigate Your Docs](https://docs.readme.com/main/docs/navigating-your-hub.md)
* [Custom Domain & SSL](https://docs.readme.com/main/docs/setting-up-custom-domain.md)
* [System Configuration](https://docs.readme.com/main/docs/system-configuration.md)
* [Custom Login Page](https://docs.readme.com/main/docs/custom-login-page.md)
* [Custom Data in Your Docs](https://docs.readme.com/main/docs/user-data-options.md)
* [Integrations](https://docs.readme.com/main/docs/integrations.md)