OpenAPI is a standardized technical specification to make describing the capabilities of the API unambiguous for both humans and machines. Why this is desirable requires a brief tangent on APIs and the problem of asymmetric information.
APIs are like contracts. The terms of the contract must be clear and unambiguous to all interested parties. An API provider creates these terms that dictate how a consumer interacts with the API. If the consumer follows the terms correctly, they'll get what they want. If they don't, someone will end up disappointed.
The trouble for the API consumer is source code is generally not accessible to them. Even if it was, it wouldn't necessarily be easy to understand. Instead, they depend on documentation or client libraries that are more like proxy contracts of the real contract. It's like asking your lawyer for a contract and their assistant copies it out by hand for you.
This problem is exacerbated as more parties become involved in managing and using the API; both internally and externally.
APIs encounter numerous problems trying to keep everyone on the same page.
- The engineer didn't implement the code and tests according to the design doc.
- The technical writer overlooked something while preparing documentation.
- The API consumer didn't integrate with the API correctly.
The poor support engineer is now stuck trying to understand if there's a bug in the code, the documentation, or the client/partner's code.
How the OpenAPI Specification Helps
The OpenAPI Specification (formerly Swagger) aims to solve all these problems and more by offering a standard, unambiguous way to describe REST APIs in a machine-readable YAML or JSON file.
This file is called an OpenAPI document and acts as your API's contract and source of truth for all interested parties to streamline development, documentation, and reduce errors. Using this document, you can do all of the following without having to write any code:
- Auto-generate documentation in multiple file formats.
- Auto-generate SDKs/client libraries in any programming language.
- Create mock servers.
- Generate and run test suites of your API.
Focusing your development efforts on an OpenAPI document encourages a design-first approach. OpenAPI documents allow you to design your API in a simple way right from the start without getting lost in code or a lengthy design doc no one wants to read.
Instead, you write a bit of YAML or JSON to define your API endpoints, schemas, requests, and responses in mere minutes. Then use that source file to generate mock servers and documentation to review with all your API stakeholders.
As someone who has read a lot of confusing API design docs, this is a game changer. There's no comparison to being able to actually see what the documentation will look like so early on and to make mock requests during the early design phase.
Since OpenAPI documents are not, strictly speaking, code, it also enables less technical stakeholders to more fully contribute as reviewers and to propose changes.
OpenAPI Ecosystem & Tools
The OpenAPI ecosystem is very active and supported by many of the largest companies in the space through the OpenAPI Initiative. It is a Linux Foundation Collaborative Project and strong proponent of open source.
The developer community around OpenAPI is also excellent. The number of tools available to support usage of OpenAPI is truly staggering.
OpenAPI.Tools has the most comprehensive list of OpenAPI tools as far as I can tell. They're an excellent repository to find tools such as
- Auto Generators: Convert your code into OpenAPI documents.
- Converters: Convert to and from OpenAPI and other API formats.
- Description Validators: Validate your OpenAPI document follows the OpenAPI Specification.
- GUI Editors: Visual editors to create OpenAPI documents.
- Mock Servers: Fake servers that respond to requests with examples set in your OpenAPI document.
- SDK Generators: Generate full client libraries in any language to make requests to your API.
- Text Editors: Get visual feedback while you write an OpenAPI document.
Where to Start with OpenAPI
OpenAPI can do so much it's not always clear where to start. I recommend starting by downloading the classic OpenAPI example document of a pet store API. Or if you already have a project in Postman, try converting it to OpenAPI with this Node package.
Then try generating HTML docs or a client library in your favorite programming language using the OpenAPI command line generator.
Otherwise, go through the long list of OpenAPI tools and see what catches your attention.