OpenAPI - API documentation standard - Boon for the software engineers

Introduction

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.

What is OpenAPI?

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:
        ....

OpenAPI is a Magic

1. You are maintaining a legacy system and you don’t have OpenAPI spec for it. Writing it from scratch manually would take a lot of time. Instead, you can use OpenAPI generators to generate specs automatically. You simply need to pass the response object to it. You can find them here - https://openapi.tools/#converters
2. The converters can also take HAR (HTTP Archive Format) file and generate a spec. You can get the HAR from chrome or firefox dev tools. Go to the network tab -> right-click on a request -> Save as HAR. List of such generators can be found here - https://openapi.tools/#auto-generators
3. You can generate boilerplate code stubs with OpenAPI spec. Yes! you heard it right! you only need to write the business logic that’s all, everything will be generated for you. There are so many generators available for every programming language. Find it here https://openapi-generator.tech. GitHub repo for the same https://github.com/OpenAPITools/openapi-generator & https://github.com/OpenAPITools/openapi-generator-cli

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.

OpenAPI UI Tools

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.

How to generate OpenAPI schema

Existing APIs

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.

New APIs

1. Create a mock API using mocky

2. Hit the request from swagger hub

3. In the history, select the request and click on “CREATE API DEFINITION”

4. This will create OpenAPI spec but does not include response.

5. To include a response, first create JSON schema from your JSON using easy json schema.

6. Copy the JSON schema and paste it here

Credits to these StackOverflow answers

https://stackoverflow.com/a/49277426/5123867

https://stackoverflow.com/a/59738617/5123867

Additional Referrences

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