What is OpenAPI Used For?

The industry has selected OpenAPI as the way forward, so let’s understand it and explore what OpenAPI includes in our OpenAPI design guide. From a technical standpoint, it is a YAML or JSON file that follows a specific document structure. You should be able to describe any REST API using a document that adheres to the OpenAPI v3 JSON schema. The primary sections of an OpenAPI spec v3 document are: Info: meta-data about the API, including its name and version Paths: relative endpoints, their operations, and responses.Security: the scheme used to authenticate calls, such as API Key or OAuth. Servers: one or more servers that can be reached with the paths.Components: reusable elements, such as error messages or responses.Tags: labels that can be used for grouping related paths External Docs: meta-data for human-readable documentation While not all of these sections are required in an API description, they can be used together to flexibly describe an API with minimal repetition. Promoting re-use means you can avoid the tedium and potential human error of find-and-replace updates.

Should OpenAPI Descriptions Use JSON or YAML?

Both JSON and YAML are supported by OpenAPI v3, and the decision is often mostly personal preference. They each have advantages for both human and machine consumers. In terms of readability, YAML is cleaner and easier for most people to decipher. It uses whitespace, colons, and newlines—a common writing syntax. By contrast, JSON has a lot of curly braces, quotes, and commas. Yet, when pretty printed, it can be similarly readable. JSON is also very easily consumed by machines. The syntax is still relatively lightweight and helps modern languages quickly parse data. The whitespacing of YAML describes the nesting of data. When accurately written, it can be quickly parsed. However, consistent spacing becomes difficult for human editors. Once a machine understands the data, outputting YAML is straightforward, but manual writing can become an effort in fighting indentations. There are good and bad things about both YAML and JSON. In addition to reading and writing issues, you’ll find some tools support only one or the other. It’s best to be familiar with both and plan to convert between them when needed.

OpenAPI Specification & OpenAPI Spec Design Guide