doctopus
Nobody likes writing docs. So to make it better, we wrote doctopus; a fluent pluggable Swagger spec builder enabling docs to be built quickly and maintained automatically.
The doctopus API provides heavy syntactic sugar over Swagger enabling re-use of common libraries and components for documentation composition.
When used in conjunction with sister libraries doctopus faciliates schema reuse for persistence, validation, and documentation reducing maintenance overhead and increasing consistency.
Overview
Way more documentation to come.
It is important to note that doctopus implements a mutable API enabling reuse of common variables and parameters to make documenting common routes easier. It is recommended to create a single instance per route file and clear params (doc.clearParams()
) when they change.
Installation
$ npm install --save doctopus
Example Configuration
const app = require('express')();
const doctopus = require('doctopus');
const docs = new doctopus.DocBuilder();
const docFactory = new doctopus.Doc();
docs.set('title', 'My Express App');
docs.add('/swagger', docFactory.get()
.group('Documentation')
.description('Gets a Swagger Specification')
.summary('Swagger')
.onSuccess(200, {
description: 'Swagger Spec',
schema: Doc.object()
})
.build());
app.get('/swagger', (req, res) => res.send(docs.build()));
app.listen('3000');
Decorator API
import {
get,
route,
group,
param,
response,
Doc,
DocBuilder,
} from 'doctopus';
@group('Cats')
class CatCtrl {
@get
@route('/cats/{id}')
@group('Orders')
public findOne(req, res) {
res.send({});
}
@get
@route('/cats')
@param({
in: 'query',
type: 'string',
name: 'name',
})
@response({
description: 'All Cats',
schema: Doc.object(),
})
public findAll(req, res) {
res.send([]);
}
}
const docs = new DocBuilder();
docs.use(CatCtrl);
Advanced Usage
Doctopus was designed with automation and re-usability in mind. To leverage automatic doc generation, we recommend using two packages that we've found to be helpful.
- joi-to-swagger - Joi Validation Object to Swagger Mapper
- For API inputs, joi is an excellent validation framework which can help define sync endpoint validation and with doctopus, you can also define your documentation using the same schemas.
- mongoose-to-swagger - Mongoose Model to Swagger Mapper
- For API outputs, often times API endpoints simply return JSON representations of mongoose models.
Doctopus allows you to simply reference the mongoose model (Doc.model('name')) and have the swagger schema automatically generated.
After you've registered your mongoose models...
const joi = require('joi');
const j2s = require('joi-to-swagger');
const m2s = require('mongoose-to-swagger');
const docs = new doctopus.DocBuilder();
const definitions = {
'Cat': {
'id': 'Cat',
'properties': {
'name': {
'type': 'string'
}
}
}
};
for(const i in mongoose.models) {
definitions[`mongoose|${i}`] = m2s(mongoose.models[i]);
}
const joiSchemas = {
Cat: joi.object().keys({
name: joi.string()
})
};
Object.keys(joiSchemas).forEach(k => {
definitions[`joi|${k}`] = j2s(joiSchemas[k]).swagger;
});
doctopus.Doc.setDefinitions(definitions);
docs.addDefinitions(definitions);
Parameter Groups
const group = {
accessToken: {
name: 'accessToken',
description: 'Client Token',
in: 'query',
required: false,
type: 'string'
},
fields: {
name: 'fields',
description: 'Fields you want returned',
in: 'query',
required: false,
type: 'string'
}
};
doctopus.paramGroup('public', group);
Doc.paramGroup('public');
Resources
Contributing
We look forward to seeing your contributions!
License
MIT © Ben Lugavere