rest-chronicle

autodocumentate rest api.

🇺🇦 Help Ukraine

I woke up on my 26th birthday at 5 am from the blows of russian missiles. They attacked the city of Kyiv, where I live, as well as the cities in which my family and friends live. Now my country is a war zone.

We fight for democratic values, freedom, for our future! Once again Ukrainians have to stand against evil, terror, against genocide. The outcome of this war will determine what path human history is taking from now on.

💛💙 Help Ukraine! We need your support! There are dozen ways to help us, just do it!

Table of Contents

• rest-chronicle
  • 🇺🇦 Help Ukraine
  • Table of Contents
  • Motivation
  • Requirements
  • Installation
  • Examples
  • Usage
    • Clients
    • Reporters
    • CLS
    • Split
  • Migration Guide
  • Contribute

Motivation

A lot of modern rest servers have a lack of up-to-date apidoc. There could be a wide number of reasons for this.

rest-chronicle can help developers keep documentation up-to-date using their existing test coverage, external clients, or even express middleware.

Requirements

To use library you need to have node and npm installed in your machine:

• node >=10
• npm >=6

Package is continuously tested on darwin, linux and win32 platforms. All active and maintenance LTS node releases are supported.

Installation

To install the library run the following command

  npm i --save rest-chronicle

Examples

Check full, ready for use, well-tested examples in the examples folder. There currently 3 examples there:

1. chat app: demonstrates apidoc generation using mocha tests with supertest module. Swagger and api-blueprint documentation files will be generated after running test.js.
2. weather app: generates apidoc as express middleware. lite markdown file will be generated after executing requests from the scenario described in client.js.
3. blog app: demonstrates apidoc generation using ava tests with axios requests. Swagger and Raml documentation files will be generated after running test.js.

Real-life projects:

• https://github.com/pustovitDmytro/sns-telegram-bot

Usage

Clients

To capture actions into the chronicle, use one of the supported clients:

Axios

import chronicle, { Axios } from 'rest-chronicle';

const axios = new Axios(chronicle);

const response = await axios({
    method : 'GET',
    url    : 'https://example.com/users',
    with   : { title: 'List of Users', group: 'Users' }
});

Express

import { middlewares } from 'rest-chronicle';
import express from 'express';

const chr = middlewares.express();
const app = express();
const router = express.Router();

router.get('/users', chr('Users', 'List of Users'), usersList);

check weather app for complete example

Supertest

import { supertest } from 'rest-chronicle';
import app from './app';

const request = supertest(app);

await request
    .with({ title: 'List of Users', group: 'Users' })
    .get('/users')
    .expect('Content-Type', /json/)
    .expect(200);

check chat app for complete example

Reporters

The package provides several reporters under the hood. General reporters API allows saving captured actions in a specific format.

To explicitly call the save method, use the next approach:

import chronicle from 'rest-chronicle';

// capture actions here

await chronicle.save('./documentation/swagger.json', { reporter: 'swagger' });

The first argument receives a file path, and the second - reporter-specific configuration.

Supported reporters:

• api-blueprint
• swagger
• raml
• template reporter - use a custom template (will be filled with handlebars)
• lite reporter - markdown file from the template will be generated. The configuration will be passed to inspect method.
• json reporter - store captured actions in JSON format with common grouping.

CLS

if you prefer using CLS (Continuation Local Storage) as context storage, enable cls namespace:

chronicle.useCLS('cls-namespace-name');

Now you can set chronicle context to cls namespace:

const ns = cls.createNamespace('cls-supertest-ns');

ns.set('chronicle-context', { title: 'create user', group: 'Users' });

Use chronicle-context as default context key, or specify the custom key as the second argument of chronicle.useCLS method:

chronicle.useCLS('my-cls-namespace', 'my-rest-chronicle-context-key');

ns.set('my-rest-chronicle-context-key', { title: 'update user', group: 'Users' });

Note: currently only supertest client recognizes cls.

Split

after all actions are captured, it is possible to split chronicle to several instances, based on dynamic criteria.

Examples:

1. move each group to separate chronicle

const splitted = chronicle.split(action => {
    return action.group;
});

2. store get requests separatelly

const splitted = chronicle.split(action => {
    return action.request.method === 'GET' ? 'get' : 'other';
});

Now splitted is an Array of chronicle instances. Each instance has id key and stores only filtered actions.

Migration Guide

Check Migration Guide to upgrade the next major version. Upgrade to minor/patch versions should happen without additional interventions. See detailed Changelog for a list of changes.

Contribute

Make the changes to the code and tests. Then commit to your branch. Be sure to follow the commit message conventions. Read Contributing Guidelines for details.