Improve API adoption with Open API Specification
December 7, 2022
Our work at DX Heroes mainly focuses on improving for both our and our clients developers. As more and more companies use APIs we also work with APIs more. We design API structures, improve their data models and polish the documentation. After working with enough APIs I started to see a recurring situation: Some companies decide to use documentation standards to improve the documentation or reusability of their API. However, they don’t allocate enough resources to do it right and the outcome is a document that doesn't match the real API, actually making developer experience worse. This pattern motivated me to write an article which sums up the benefits and challenges of using an OpenAPI Specification (or other formats used to describe an API).
What is OpenAPI Specification
OpenAPI Specification is the most common standard for documenting, visualizing and consuming REST based APIs, technically it is a YAML or JSON file with a specific structure. It was first introduced as Swagger and in 2015 was donated to the Linux Foundation. Now it is an open source project maintained by the OpenApi initiative which is a consortium of experts that are focused on creating, evolving and promoting a vendor neutral API description format [1]. Over the years a lot of tooling in the API field started using OpenApi documents as an input. Currently, you can use OpenApi documents as input in tools that can generate client or server-side code, test APIs, mock them and even validate for security vulnerabilities. Full list of tools can be found at the OpenApi page [2]. You can use an OpenApi document to do a lot of useful things, however a lot of companies don't have any OpenApi specification or their OpenApi specification does not match their API.
Why is OpenAPI important for you
Good quality OpenApi specification for your API can simplify work for both the developers and consumers. Here is a list of only a fraction of potential benefits of OpenApi Specification:
- API developers, together with business stakeholders can use OpenApi Specification to iterate on API design, think about data structures, and plan new features.
- API developers can use Open Api with tolling to test and validate actual implementation.
- OpenApi also enables developers to create for your API which helps the consumer.
