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 conjuction with sister libraries doctopus faciliates schema reuse for persistence, validation, and documentation reducing maintenance overhead and increasing consistency.
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.
$ npm install --save doctopusconst 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');import {
get,
route,
group,
param,
response,
Doc,
DocBuilder,
} from 'doctopus';
// set default for all controller methods
@group('Cats')
class CatCtrl {
// http get request
@get
// set route
@route('/cats/{id}')
// override group of a specific method
@group('Orders')
public findOne(req, res) {
res.send({});
}
@get
@route('/cats')
// add a param
@param({
in: 'query',
type: 'string',
name: 'name',
})
// declare response
@response({
description: 'All Cats',
schema: Doc.object(), // schema, see schema api
})
public findAll(req, res) {
res.send([]);
}
}
const docs = new DocBuilder();
// docBuilder instance will read the docs
docs.use(CatCtrl);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 = {
// you can define custom definitions in line or reference from another file if you choose
'Cat': {
'id': 'Cat',
'properties': {
'name': {
'type': 'string'
}
}
}
};
// automatically register // namespace all mongoose models
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;
});
// enable Reflection in doctopus api (Doc.pick('RegisteredModel', 'Property')))
doctopus.Doc.setDefinitions(definitions);
// add definitions to swagger definitions
docs.addDefinitions(definitions);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);
// later
Doc.paramGroup('public');- API Docs
- Helpful Tutorial
- swagger-jsdoc - annotation helper
- Official Swagger Documentation
We look forward to seeing your contributions!
MIT © Ben Lugavere
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent