With the increasing number of adoption towards service-oriented architecture and for better integrations with external systems, it became a necessity to write Restful APIs for our services. While building so we might often find several challenges such as,
- Standard & Consistent API design
- Better documentation
- Client Libraries
- Playground (better developer experience)
So while writing APIs, we have to make sure it sticks to a standard design principle, update documentation (hosted elsewhere) and finally write client libraries (harder if you have to support multiple languages). Doing all of this manually is a painful job.
Likely we have OpenAPI Specification (formerly known as swagger), which offers us a standard, language-agnostic interface to write RESTful APIs which allows both humans and computers to understand the service capabilities.