Create docs for your API using functional tests.
- Connect
the-owl
middleware to your Express.js application - You write functional tests for your API endpoints
- Markdown files for each test file are created under
docs/
folder
Pretty interesting, right? Follow along to learn more.
Install the package:
npm install --save-dev the-owl
- Step 1: Connect the "information collection middleware" on your Express server.
const bodyParser = require('body-parser');
const express = require('express');
const theOwl = require('the-owl');
exports.server = {
close(api) { ... },
listen(app, port) { ... },
async start(port = process.env.PORT) {
const app = express();
//// STEP 1: Connect the Express middleware so request/response information can be collected.
theOwl.connect(app);
// middlewares
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: false }));
// routes
app.get('/health', (req, res) => res.status(200).send('OK'));
app.get('/users', (req, res) => res.status(200)
.json(
[{ id: 1, name: 'John' }, { id: 2, name: 'Paul' }]
)
);
const api = await this.listen(app, port);
return api;
},
};
- Step 2: Set custom headers on requests that you want to collect information;
- Step 3: Set test hook to "createDocs" after all tests have runned.
const got = require('got');
const test = require('ava');
const theOwl = require('the-owl');
const { closeApiOpenedOnRandomPort, startApiOnRandomPort } = require('../__helpers__');
test.before('start server', async t => {
t.context.endpointOriginalPath = `/health`;
await startApiOnRandomPort(t);
});
//// STEP 3: Call "createDocs" method after all test cases have runned.
//// STEP 4: Run the script "CREATE_DOCS=true npm test" on terminal.
test.after('create api docs', t => theOwl.createDocs());
test.after.always('close server', t => closeApiOpenedOnRandomPort(t));
test('(200) returns the application status', async t => {
const response = await got(t.context.endpointBaseUrl , {
retry: { retries: 0 },
headers: {
'your-custom-header': 'Notice how it appears on generated doc but "theOwl" headers doesn\'t!',
//// STEP 2: Send "theOwl" headers on requests which information must be collected to generate api docs.
//// NOTE: Information will not be collected if "theOwl" headers are not correctly sent.
// Option 1: use the utility function to build the headers.
...theOwl.buildHeaders(t.title, t.context.endpointOriginalPath),
// Option 2: you set the headers manually.
// 'x-test-name': t.title,
// 'x-req-original-path': t.context.endpointOriginalPath,
},
});
t.assert(response.statusCode === 200);
t.assert(response.body === 'OK');
});
On terminal
Run your test suit:
CREATE_DOCS=true npm run test
The docs/
folder will be created (if doesn't exists) with the results:
Enforce functional tests development by earning something tangible from it.
Usually, API contract changes are done on code and documentations gets obsolete, as it's usually a .yml
or @jsdoc
that developers forget to update or it uses boring specific markup rules.
This package was built with the mindset that all changes should be made in code.
Please see the files in the /documentation
directory:
Please refer to this document.