easy-api-doc

Good, updated, and easy API documentation for free and for all! ✊ 📖

Table of content

• easy-api-doc
  • Table of content
  • Installing
  • Motivation
  • How it works?
    • Document setup
    • Path and response definition
    • Building using a super agent response
    • Building using a native node.js HTTP response
    • Building manually
    • Generating the document
  • Contributing
  • Versioning
  • Authors
  • License
  • Next Steps

Installing

npm i -D easy-api-doc

Motivation

API documentation should be a democratic and accessible thing. It helps others and yourself to understand how to use the API and its possible behaviors more easily. But unfortunately very often the API docs are out of date and neglect, causing more confusion rather than help people to understand how to use the desired API.

For this reason, easy-api-doc was created! To help developers to build and maintain a good and updated API document, following the Open API v3 specification, with a minimum effort way.

How it works?

easy-api-doc exposes an API to create the Open API v3 (aka Swagger) document in the JSON or YAML format. Using a semantic builder approach, you can plug the document definition anywhere you think it fits better inside your code. For example, you can use it to be a "reward" for the integration tests implemented, this way you will always have an updated and validated API document for free!

const doc = new OpenAPIDocument('api.yml', {
  version: '1.0.0',
  title: 'My awesome API',
});

doc
  .path('/status')
  .verb('head', { tags: ['infra'] })
  .fromSuperAgentResponse(res, '');

doc.writeFile();

Then you can combine it together with a library like swagger-ui-express to expose a API docs page.

Document setup

The definition and possible attributes for the OpenAPIDocument can be found here.

You can have an util file with the following content. Exporting the document instance:

import { OpenAPIDocument } from 'easy-api-doc';

import { version } from '../../package.json';

export const doc = new OpenAPIDocument('./doc/api-reference.yml', {
  version,
  title: 'My awesome API',
  description: 'Rest API definitions',
});

Path and response definition

With a OpenAPIDocument instance, you will be able to define a new path using the following method:

path(path: string, options?: { summary?: string; description?: string }): PathBuilder;

And with a PathBuilder instance, you can define a new verb using the following method:

verb(verb: HttpVerb, options?: ResponseBuilderOptions): ResponseBuilder;

And then you can define a possible response using the following methods:

Building using a super agent response

Many developers like to use the supertest library to implement theirs integration tests. With supertest, you can simulate calls to a given HTTP server and it will respond using superagent's Response! We can take advantage of it to generate our API docs for sure!

import { expect } from 'chai';
import supertest from 'supertest';
import faker from 'faker';
import { OK } from 'http-status';

import App from '@App';
import { doc } from '@helpers/documentation';

describe('Feature test', function () {
  after(function () {
    doc.writeFile().catch(console.error);
  });

  describe('Integration Tests', function () {
    it('should return 200 OK', function (done) {
      const body = {
        foo: faker.random.word(),
      };

      supertest(app)
        .post('/')
        .send(body)
        .set('Content-type', 'application/json')
        .expect(OK)
        .end((err, res) => {
          expect(err).to.be.null;

          doc
            .path('/')
            .verb('post', { requestBody: { content: body, mediaType: 'application/json' }, tags: ['tags'] })
            .fromSuperAgentResponse(res, 'test validated');
          done();
        });
    });
  });
});

For the previous example, you will end up with something similar to the following YAML file at the end of your test execution, which will be automatically be updated if you change something (bodies, headers, status code, etc).

info:
  version: 0.1.0
  title: My awesome API
  description: Rest API definitions
paths:
  /:
    post:
      responses:
        '200':
          description: test validated
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  bar:
                    type: string
                    example: random-word
          headers:
            content-type:
              schema:
                type: string
              example: application/json; charset=utf-8
            content-length:
              schema:
                type: string
              example: '941'
            x-response-time:
              schema:
                type: string
              example: 1.291ms
            date:
              schema:
                type: string
              example: 'Tue, 13 Apr 2021 18:36:09 GMT'
        tags:
          - auth
        requestBody:
          content:
            application/json:
              schema:
                type: object
                properties:
                  foo:
                    type: string
                    example: Quinton_Shanahan26
openapi: 3.0.3

Building using a native node.js HTTP response

If you prefer to keep away from third parties dependencies, easy-api-docs also provides to you a way to take advantage of the native node.js HTTP response:

import { doc } from '@helpers/documentation';

const app = createServer((req, res) => {
  const url = new URL(req.url);

  res.setHeader('Content-Type', 'application/json');
  res.writeHead(200);

  doc.path(url.pathname).verb(req.method).fromServerResponse(res, 'description', { foo: 'bar' });
});

Building manually

If you just want to build a documentation manually, easy-api-docs provides an API to do so:

const doc = new OpenAPIDocument('./api.yaml', { title, version });

doc
  .path('/foo')
  .verb('get')
  .status(200)
  .withContent('application/json', { example: 'Super cool value', schema: { type: 'string' } });
doc
  .path('/foo')
  .verb('get')
  .status(404)
  .withContent('application/json', { example: 'Not found 😢', schema: { type: 'string' } });
doc
  .path('/bar')
  .verb('post')
  .status(201)
  .withContent('application/json', { example: 'Persisted!', schema: { type: 'number' } });

doc.writeFile();

Note: you should only invoke the fromServerResponse method after you set the response status code, otherwise it won't be able to help you that much.

Generating the document

After you get your OpenAPIDocument instance, it is simple like calling a function to generate you document file.

writeFile(format: 'json' | 'yaml' = 'yaml'): Promise<void>

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Pedro Mutter - Initial work - MutterPedro

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE file for details

Next Steps

• [ ] Enable Security component setup
• [ ] Builder using Axios response
• [ ] Builder using Express request/response
• [x] Builder using native HTTP request/response
• [x] Builder using manual definition