Best DX to write OpenAPI documentation

Creating an OpenAPI documentation can look boring or hard.
But if you carefully design the workflow, it can be delight and easy.

In this article, I will explain how creating a OpenAPI documentation at Woovi works.

Colocation of Code and Documentation

The first thing we thought when designing this workflow is that documentation should be colocated besides the code.
If you check the image above, the GET /charge api is besides chargeGet.yml documentation file.

Writing some yml

/api/v1/charge/{id}:
  get:
    tags:
      - charge
    summary: Get one charge
    parameters:
      - name: id
        in: path        
    responses:
      '200':
        description: The charge retrieve using the given ID
        content:
          application/json:
            schema:
             ...             

We write documentation using yml format. We describe endpoints, tags, components, enums, and every thing that an API documentation needs.

Bundling the yml files

OpenAPI editor does not accept many files, they just accept 1 single yml or json file. So we need to find a way to bundle all our separate yml documents into a single one.

For this task, we are going to use swagger-jscode. It says that it is to write Swagger, old name of OpenAPI, inside jsdoc, like below

/**
 * @openapi
 * /:
 *   get:
 *     description: Welcome to swagger-jsdoc!
 *     responses:
 *       200:
 *         description: Returns a mysterious string.
 */
app.get('/', (req, res) => {
  res.send('Hello World!');
});

It sounds like a good idea, but does not scale if your documentation is too big. Luckly, this package also bundle .yml files.

This is the command line call that we use to bundle our documentation

yarn swagger-jsdoc -d wooviConfig.js src/charge/**.yml -o woovi-openapi.yml

This command generates a final woovi-openapi.yml that contains the content of all .yml files.

In closing

When you invest in DX, when you make something easy, everybody starts doing it.
Documentation should not be a pain, documentation should be part of our workflow.
Documentation is communication.

Woovi
Woovi is a Startup that enables shoppers to pay as they like. To make this possible, Woovi provides instant payment solutions for merchants to accept orders.

If you want to work with us, we are hiring!

Photo by Duy Pham on Unsplash