Good, updated, and easy API documentation for free and for all! ✊ 📖
npm i -D easy-api-docAPI 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.
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.
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',
});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:
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.3If 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' });
});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.
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>Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
We use SemVer for versioning. For the versions available, see the tags on this repository.
- Pedro Mutter - Initial work - MutterPedro
See also the list of contributors who participated in this project.
This project is licensed under the MIT License - see the LICENSE file for details
- Enable Security component setup
- Builder using Axios response
- Builder using Express request/response
- Builder using native HTTP request/response
- Builder using manual definition