the-owl

Create docs for your API using functional tests.

How does it works

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

Usage

Install the package:

npm install --save-dev the-owl

On "examples/01-minimal" server file:

• 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;
  },
};

On "examples/01-minimal" functional test file:

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

Motivation

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.

Documentation

Please see the files in the /documentation directory:

• 01. API
• 02. Process variables

Contributing

Please refer to this document.