Create documentation for the API of an express app. As an endpoint in an express app.
npm install api-doc
var apiDoc = require('api-doc');
app.get('/apidoc/', apiDoc(app)); //you need to pass the express appvar apiDoc = require('api-doc');
var options = {
showNonPublic: true
cache: false
}
app.get('/apidoc/', apiDoc(app, options));var apiDoc = require('api-doc');
var options = {
showNonPublic: true
cache: false
}
var docs = apiDoc.getApiDocs(app, options);showNonPublic, boolean, defaultfalse. If set totrueeven endpoints that do not have thepublic:truewill be documented. This can be used in development mode for example to see all endpoints in your docs.cache, boolean, defaulttrue. If set tofalsethe api documentation will be extracted for the express app on every call.
All endpoints are documented automatically. But you have to augment the documentation inline in your code to make it useful.
The documentation of the resources is generated directly from the Node.js code. We've implemented a way to annotate endpoints (middleware) with various extra documentation.
When you create a resource you document it by adding a .doc to the endpoint function. The .doc property can contain information about.
- A description.
- What the resource consumes,
application/jsonfor example. - What the resource produces,
application/jsonfor example. - The HTTP status codes the resource can return and a short description of what that code means,
404 = Id not foundfor example. - Is this endpoint public? Set to the
publicproperty totrueif you want this endpoint documented. Here is an example of adding.docto an endpoint function.
module.exports = function (http) {
http.get('/customers/schema', returnSchema);
returnSchema.doc = {
produces:'application/json',
description: 'The JSON schema of customers',
public: true,
httpStatus:{
'200':'JSON with json schema'
}
};
function returnSchema(req, res) {
res.json(customerSchema);
}
}When you add this, this information will automatically be added to the documentation, both in the HTML and in the JSON.
{
produces:'application/json',
consumes:'application/json',
httpStatus:{
'200':'JSON blah blah',
'412':'Invalid id format'
}
}There is no need to document that a resource can return http status code 500, this should be documented one place, and is general for all the endpoints.
Usually you will want a general solution for automatically adding authorization to an endpoint, so you do not have to manually document an endpoint with 403's
When a resource makes use of middleware that can cause an error and return a HTTP status code (validation for example), that middleware should be documented itself. Example:
function getSchemaValidateFunction(schema) {
val.doc = {
consumes: 'application/json',
httpStatus:{
'400': 'validation error(s)'
}
};
return val;
function val(req, res, next) {
//validate according to jsv schemas
var report = schema.validate(req.body, schema);
if (!report.valid) {
//we only return something when there is an error
return next(errors.jsonValidationError(report.errors));
}
next();
};
}Above we know that the errors.jsonValidationError returns HTTP status code 400, so we document this.
module.exports = function returnBody(){
success.doc = {
produces: 'application/json',
httpStatus:{
'200': 'JSON with the entity as it would be stored, no id though'
}
};
return success;
function success(req, res) {
res.json(req.body);
}
};This middleware returns the JSON with the entity as it would be stored, no id though with HTTP status
code 200 (res.json), so we document this.
When both the above middelwares are used in a resource like this:
module.exports = function (http) {
http.post('/customers/validate',
getSchemaValidateFunction(customerSchema),
returnBody()
);
}The API documentation will extract information from both middelwares and document that this resource can return both HTTP status code 400 and 200, and both produces and consumes application/json.
NOTE: If more than one middleware function returns the same HTTP status code, for example using two validate middelwares that bot return HTTP status code 400. The description of the first one will currently be overwritten by the description of the second one.
Notice that if your middleware calls other JavaScript functions in its' body, adding .doc to those functions
will not work. Example:
module.exports = function (app) {
app.get('/myendpoint/something', returnX);
function returnX(req, res) {
req.mongo.getCollection('appUsers', gotUserCollection);
//This below DOES NOT WORK, you need to add .doc to top level of middleware
gotUserCollection.doc = {
produces:'application/json',
httpStatus:{
'200':'JSON'
}
};
function gotUserCollection(err, collection){
if(err) return next(errors.mongoError('Could not get collection'));
//some code...
}
}
}Merge two documentations of two middleware functions.
When writing middleware it is recommended that you accept a doc property in the options. And use the mergeDocs function to merge
the doc property of your middleware function with the doc passed in options. Like this:
var apiDoc = require('api-doc');
module.exports = function myMiddlewareFactory(options) {
myMiddleware.doc = {
produces:'application/json',
httpStatus:{
'200':'JSON blah blah'
}
};
if (options && options.doc) {
myMiddleware.doc = apiDoc.mergeDocs(myMiddleware.doc, options.doc);
}
return myMiddleware;
function myMiddleware(req, res, next) {
//implementation
}
};The documentation returned has this kind of format.
{
//Root level properties are the routes in your express app
//Required
'/customers':{
//One of HTTP methods (express): get, put, del or post
//Required
get:{
//Description of this endpoint
//Optional
description:'list all customers',
//data format produced
//Optional
produces:'application/json',
//TODO: Add description for: httpStatus
//Optional
httpStatus:{
//Description of data returned when http status code is 200
//Optional
200:'A list of customers',
//Description why 412 can be returned
//Optional
412:'value'
},
//string representing an example of the (pretty-printed) JSON this endpoint produces
//Optional
example:'value'
},
//One of HTTP methods (express): get, put, del or post
//Required
post:{
//Description of this endpoint
//Optional
description:'creates a new customer',
//data format produced
//Optional
produces:'application/json',
//type of accepted by endpoint
//Optional
consumes:'application/json',
//TODO: Add description for: httpStatus
//Optional
httpStatus:{
//Description of data returned when http status code is 200
//Optional
200:'A list of customers',
//Description why 400 can be returned
//Optional
400:'value',
//Description why 412 can be returned
//Optional
412:'value'
},
//string representing an example of the (pretty-printed) JSON this endpoint produces
//Optional
example:'value'
}
}
}