Nihilist Pocket Monsters

    api-doc

    4.0.3 • Public • Published

    api-doc Build Status

    npm package

    Create documentation for the API of an express app. As an endpoint in an express app.

    npm install api-doc
    

    Usage

    var apiDoc = require('api-doc');
     
    app.get('/apidoc/', apiDoc(app)); //you need to pass the express app
     

    Options

    var apiDoc = require('api-doc');
    var options = {
        showNonPublic: true
        cache: false
    }
     
    app.get('/apidoc/', apiDoc(app, options));
     

    Getting api docs from express app without the middleware

    var apiDoc = require('api-doc');
    var options = {
        showNonPublic: true
        cache: false
    }
     
    var docs = apiDoc.getApiDocs(app, options);
     
    • showNonPublic, boolean, default false. If set to true even endpoints that do not have the public:true will be documented. This can be used in development mode for example to see all endpoints in your docs.
    • cache, boolean, default true. If set to false the api documentation will be extracted for the express app on every call.

    Documenting your API

    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.

    Documenting a resource.

    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/json for example.
    • What the resource produces, application/json for example.
    • The HTTP status codes the resource can return and a short description of what that code means, 404 = Id not found for example.
    • Is this endpoint public? Set to the public property to true if you want this endpoint documented. Here is an example of adding .doc to 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.

    The .doc format

    {
        produces:'application/json',
        consumes:'application/json',
        httpStatus:{
            '200':'JSON blah blah',
            '412':'Invalid id format'
        }
    }

    Special status codes you should not use

    500 - Internal server error

    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.

    403 - Unauthorized

    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

    Documenting express middleware

    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:

    Customer validator middleware

    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.

    Customer returnBody middleware

    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.

    A resource with middleware will get documentation from middleware added

    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.

    Documentation must be at the root level of the middelware

    Notice that if your middleware calls other JavaScript functions in its' body, adding .doc to those functions will not work. Example:

    THIS DOES NOT WORK##

    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...
            }
        }
    }

    mergeDocs

    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
        }
    };

    Example of JSON returned by api-doc

    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'
            }
        }
    }

    License

    MIT

    Keywords

    none

    Install

    npm i api-doc

    DownloadsWeekly Downloads

    81

    Version

    4.0.3

    License

    MIT

    Unpacked Size

    17 kB

    Total Files

    6

    Last publish

    Collaborators

    • bifrost
    • bubenshchykov
    • eagleeye
    • ebdrup
    • fizker
    • jonatanpedersen
    • kapetan
    • mpushkin
    • mujichok
    • wtfil