Introduction to OpenAPI

OpenAPI is a standard specification format for describing HTTP APIs.

An OpenAPI file describes the API in a structured way so that tools can understand the endpoints, methods, request payloads, response payloads, headers, status codes, and authentication rules.

OpenAPI Is The Specification

OpenAPI is the standard. It is not a single tool or product.

An OpenAPI specification can be written as JSON or YAML. The file can then be used by many different tools, including REST clients, documentation generators, API validators, mock servers, SDK generators, and browser-based interfaces.

Swagger is one family of tools that works with OpenAPI. Swagger UI is a free-to-use browser interface that can render an OpenAPI file and let people issue requests from a web page.

What Tools Can Do With OpenAPI

Tools can read an OpenAPI file to:

create request templates in REST API clients
generate interactive API documentation
compare API responses with the documented response structure
create mock API servers
generate SDK or client code
support exploratory testing by showing available endpoints and data shapes

The more complete the OpenAPI file is, the more value those tools can provide.

Viewing An OpenAPI File

You can view an OpenAPI file in any text editor because it is plain JSON or YAML.

If you are new to OpenAPI then a dedicated tool is easier because it can render the file as navigable documentation.

Examples on this site:

Both APIs also expose versioned OpenAPI JSON files:

OpenAPI v 3.0 JSON for tools that support OpenAPI 3.0
OpenAPI v 3.1 JSON, which is the default openapi.json version
OpenAPI v 3.2 JSON, which can describe QUERY as a native HTTP method

OpenAPI For Testing

When testing, the OpenAPI file is a useful source of truth, but it is not the same as the running API.

The specification can help you identify:

documented endpoints
expected request payloads
expected status codes
required fields
content types
unsupported methods

It can also help you spot gaps. If the running API behaves differently from the OpenAPI description then either the API or the documentation may need to change.

Standard And Permissive Files

API Challenges provides two styles of OpenAPI output.

The standard validation files describe intended usage. These are useful when you want tools to guide you through normal valid requests.

The less-validating, permissive files are useful for testing because they relax some of the constraints that browser tools and REST clients might otherwise enforce before a request is sent.

Examples:

OpenAPI In REST Clients

Most REST clients can import an OpenAPI file and create a starter collection of requests.

This is often the most flexible testing workflow because REST clients are not limited by browser security rules in the same way as browser-hosted API interfaces.

OpenAPI Tools

The OpenAPI ecosystem has many tools for validation, mocking, documentation, code generation, and test support.

Related Swagger Page

Read Swagger UI and Swagger tooling when you want to use a browser interface to explore an OpenAPI file.