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 schema.
The primary sections of an OpenAPI spec v3 document are:
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.
While OpenAPI v3 is the most recent version of OpenAPI, it replaced OpenAPI v2 - previously known as Swagger. The newer version provides a simpler way to describe APIs, while also offering more flexibility. Because there were a lot of legacy Swagger documents, it’s important to have a compatible community-owned version. But API practitioners wanted to move the OpenAPI specification forward with OpenAPI v3.
One of the biggest differences between OpenAPI v2 and v3 is the
components object. For example, responses were their
own distinct object in OpenAPI v2, whereas they are now organized under components. Components are reusable objects,
which include schemas, request bodies, parameters, response information, security schemes, and newer concepts like
links, and callbacks.
There are a handful of other components, some of which didn’t directly exist in OpenAPI v2. Two notable new components are callbacks and headers. Callbacks can be used with Webhooks and other asynchronous technologies. Headers, while describable in OpenAPI v2, are now able to be reused more easily.
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.
Whether wrestling with data formats or spinning up mock servers, there are tools to improve your API design experience. Start from scratch or import an existing description, then start building and sharing with your team. Stoplight Studio - our free visual OpenAPI Designer provides a design-first suite of tools to help you build great APIs.