DEV Community

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

Posted on • Edited on

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' }]); });
Enter fullscreen mode Exit fullscreen mode

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(); }); }); });
Enter fullscreen mode Exit fullscreen mode

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(); }
Enter fullscreen mode Exit fullscreen mode

package.json

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

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"
Enter fullscreen mode Exit fullscreen mode

Outdoc can also auto generate tags for multiple endpoints.

Check more options and examples in Github https://github.com/dapi-labs/outdoc

Top comments (0)