I create a tool for helping me generate the API document from test cases

#node #showdev #productivity #tooling

Writing an API document is something I hate, and writing an OpenAPI document from scratch is a nightmare.

I checked some auto-api-generation tools and they all need me to modify my codes by adding comments or decorators. I personally don't like it because I wanna keep my code as clean as possible.

Then I was thinking if we could generate an API document based on the unit test because usually the unit test covers all cases of the API, we just need a program to understand the test cases and generate the API document.

So I build Outdoc and here is an example for an express application:

app.js

const express = require('express');
const app = express();

app.get('/projects', (req, res) => {
  res.json([{
    id: '1',
    name: 'project v1'
  }, {
    id: '2',
    name: 'project v2'
  }]);
});

app.test.js

const request = require('supertest');
const app = require('./app.js');

describe('api testing', () => {
  it('should able to find all', (done) => {
    request(app)
      .get('/projects')
      .set('x-api-key', 'outdoc-test')
      .expect(200)
      .end(function(err, res) {
        if (err) throw err;
        done();
      });
  });
});

For using Outdoc, we simply add a few codes into app.js and run the script.

app.js

const express = require('express');
const app = express();

// New added for using Outdoc
if (process.env.NODE_ENV === "test") {
  const { OutDoc } = require('outdoc');
  OutDoc.init();
}

package.json

{
  "scripts": {
    "test": "mocha *.test.js",
    "gen-doc": "outdoc npm test"
}

By running npm run gen-doc, we get an api.yaml as the following

openapi: "3.0.1"
info:
  title: "API Document"
  version: "1.0.0"
paths:
  /projects:
    get:
      parameters:
        - in: "header"
          name: "x-api-key"
          example: "outdoc-test"
          schema:
            type: "string"
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                type: "array"
                items:
                  type: "object"
                  properties:
                    id:
                      type: "string"
                      example: "1"
                    name:
                      type: "string"
                      example: "project v1"