Customer StoriesReadMe Blog

# What Is OpenAPI (Formerly Known As Swagger)?

From [the OpenAPI Specification repository](πŸ”—ο»Ώ):

The **OpenAPI Specification (OAS)** is a community-driven open specification within the [OpenAPI Initiative](πŸ”—ο»Ώ)... [that] defines a standard, programming language-agnostic interface description for [REST APIs](πŸ”—ο»Ώ).

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](πŸ”—ο»Ώ) and read about the differences between Swagger v2.0 and OAS v3.0 [**on our blog**](πŸ”—ο»Ώ).

To see our most up-to-date support for the OpenAPI Specification (including our support for OAS v3.1), see [our 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](πŸ”—ο»Ώ) and [Swagger](πŸ”—ο»Ώ), you can also import [Postman Collections](πŸ”—ο»Ώ). Postman Collections are converted to OpenAPI using [`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](πŸ”—ο»Ώ) v3.0.x/v3.1

  • ο»Ώ[Swagger](πŸ”—ο»Ώ) v2.0

  • ο»Ώ[Postman Collections](πŸ”—ο»Ώ) v2.0/v2.1

    • Anytime a Postman collection is imported, it's converted to OpenAPI using [`postman-to-openapi`](πŸ”—ο»Ώ) β€” check out [their docs](πŸ”—ο»Ώ) 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.