OpenApi Specification (OAS) for API development
What is OpenApi Specification?
It’s a simple standard for declaring, defining and visualizing restful api interfaces via OpenAPI Specification document (earlier known as SWAGGER Specification).This OpenAPI Specification is language agnostic, It helps developers and computers to understand apis with none or minimal human intervention.
OpenApi specification can be used to view, generate api documentation, service code and client code in different languages via SWAGGER tools. SWAGGER tools are open source tools built to generate Service/Client code in different languages via OpenAPI Specification .
Why should we use it?
Cost effective ( Generates code via tool) -SWAGGER Tool can generate code automatically via OpenAPI Specification file
-Server Code
-Client Code
-Documentation
Speeds up integration and development - Since OpenAPI Specification file contains Request, Response, Failures of service. Which makes it clear and easy to understand for developers and computers for integration with none or minimal help.
Better Quality API - Open Api specification defines request, response , failures and it’s data type. It also contains example for api request and responses. Since it starts new api development with document first approach , which gives a good start to brainstorm about all the edge cases , request and response for an api including behavior in failure cases. This document first approach improves the quality of api.
Simple and usage reusable construct - It’s simple and easier to create OpenApi Specification for a service. It’s data structure and request, response constructs are re-usable within Open API Specification file. It means cleaner Open API Specification file with less effort.
How should we use it?
Existing API - Create Open Api Specification (OAS) based on api interface implementation and get rid from maintaining documentation and service client.
New API - In this scenario , We should first write an Open Api Specification for api interfaces. Which will contain Request, Response, Failures, their data type and data structures. Later we can use SWAGGER tools to generate service and client code automatically via tool in different languages.