OpenAPI overview and best practices

OpenAPI is a standard for describing RESTful APIs. OpenAPI defines an API’s core elements, like endpoints, request and response data formats, authentication methods, and more.

Several versions of the OpenAPI Specification are in circulation: 2.0 (known as Swagger), 3.0, and 3.1.

Speakeasy supports OpenAPI versions 3.0 and 3.1 and recommends OpenAPI version 3.1 for all projects. The advantage of OpenAPI version 3.1 is its full compatibility with JSON Schema , providing access to a large ecosystem of tools and libraries.

OpenAPI best practices

OpenAPI offers extensive flexibility and can describe any HTTP API, including REST APIs and even RPC-based calls. The OpenAPI Specification provides several valid approaches to achieving the same result.

With this flexibility, constructing an OpenAPI document suitable for code generation requires careful consideration. Speakeasy recommends following specific best practices when writing OpenAPI documents. The sections below outline key points to consider when creating an OpenAPI description.

Extending OpenAPI

The OpenAPI Specification lacks an exhaustive vocabulary for describing API functionality. To overcome specification gaps, add extension fields to an OpenAPI document that describe additional metadata and functionality.

Extensions typically follow a naming format of x-<vendor>-<function>, where <vendor> is the name of the vendor or tool that created the extension and <function> is the goal accomplished by the extension.

A range of Speakeasy extensions help prepare OpenAPI documents for code generation. Some of the most commonly used extensions are described below.