Your product manager brought a new product requirement. Frontend engineers and you (backend engineer) finalized a solution. They asked you for an API contract. You created a google doc (or confluence) and gave it to them. The contract changed later and you update the code as well as the document. Wouldn’t it be so nice if the documentation also lives in your code repository and automatically updates along with your code changes? That’s where OpenAPI comes in.
OpenAPI is a standard for defining the documentation of backend APIs. It is in the form of a file called a specification document. It can be in YAML or JSON format. OpenAPI sets standard syntax to define an API contract. You can read more about it here.
An example of an OpenAPI spec looks like this. A more detailed explanation of each field can be found here.
openapi: 3.1.0 info: title: Order Management System description: | Order Management provide APIs to create, cancel, deliver and reject orders version: 1.0.0 paths: /api/v1/order: post: summary: Creates a new order description: creates a new order paramters: .... responses: ....
With the above tools, writing an API is very easy in 2 steps. Create a sample JSON response structure of your API. Generate OpenAPI spec and pass it to the generators to generate stubs.
There are two popular UI tools generated using OpenAPI spec. One is a widely used and popular swagger. Another is Redoc. The integration of these tools with any programming language is very easy. The guides for them are present on their respective websites.
If there are existing APIs in production, download HAR (from chrome/firefox devtools or use mitmproxy) and use HAR to OpenAPI tools to generate schema.
Create a mock API using mocky
Hit the request from swagger hub
In the history, select the request and click on “CREATE API DEFINITION”
This will create OpenAPI spec but does not include response.
To include a response, first create JSON schema from your JSON using easy json schema.
Copy the JSON schema and paste it here
Credits to these StackOverflow answers
OpenAPI Homepage - https://www.openapis.org
OpenAPI Spec - https://spec.openapis.org/oas/v3.1.0
OpenAPI Documentation - https://oai.github.io/Documentation
OpenAPI Generators - https://openapi-generator.tech
OpenAPI Tools - https://openapi.tools