Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including express-list-endpoints-descriptor with all npm packages installed. Try it out:

var expressListEndpointsDescriptor = require("express-list-endpoints-descriptor")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

express-list-endpoints-descriptor v1.0.13

list all Endpoints registered into an express app with description user defined to build documentation

Simple, lightweight, fast and customizable

Extends express routes adding descriptor function. In descriptor you can add the object representing the parameters that you need.

app.get('/books', function (req, res) {
    res.send("My fantastic book");
}).descriptor({
    name : 'Retrieve a fantastic book',
    params : []
});

Basic example

var express = require('express');
var api = require('express-list-endpoints-descriptor')(express);
var app = express();

app.get('/user', function (req, res) {
    res.json({user:true})
}).descriptor({
    name : 'Get list of users'
});

app.get('/api', function (req, res) {    
    res.send(api.listAllEndpoints(app));
}).descriptor({
    name : 'My first API documentation'
});

app.listen(8080, function () {
    console.log('Example app listening on port 8080!');
});

Browsing http://localhost:8080/api will return

[
    {
        "path": "/user",
        "methods": ["GET"],
        "descriptor": [{"name": "Get list of users"}]
    },
    {
        "path": "/api",
        "methods": ["GET"],
        "descriptor": [{"name": "My first API documentation"}]
    }
]

Inside descriptor object you will find the object that you defined inside the descriptor function after route definition.

Keys definition

* **`path`**: `[STRING]` * **`methods`** : `[ARRAY of strings]` Methods for the same endpoint e.g. `['GET','POST']` * **`descriptor`**: `[ARRAY of objects]` Object user defined inside descriptor function (in the same order of `methods` array) `[{name:'description of /users with method get'}`,
`{name:'description of /users with method post']`

Mehods

  • api.listAllEndpoints(server) retrieve all the mapped Express APIs even if the ones that were not extended by the descriptor function. The object server is an instance of express.
  • api.listEndpoints(server) : retrieve only the mapped Express routes, that extend with the descriptor function. The object server is an instance of express.

Retrieve all endpoints list

app.get('/apis', function (req, res) {
    res.send(api.listAllEndpoints(app));
}).descriptor({
    name : 'Retrieve APIs documentation'
});

Retrieve endpoints list that has been extended

app.get('/apis', function (req, res) {
    res.send(api.listEndpoints(app));
}).descriptor({
    routedescr : 'Retrieve APIs list only from routes that have it'
});

Usage

The express-list-endpoints-descriptor module allows to create documentation for Express APIs. Works with Your router instance (router) or your app instance (app).

Example - APP instance

var express = require('express');
var api = require('express-list-endpoints-descriptor')(express);
var app = express();

app.get('/user/:ID', function (req, res) {
    res.json({user:true})
}).descriptor({
    name : 'Get details about user',
    params: {ID:'STRING'}
});

//will not appear on endpoints = api.listEndpoints(app);
app.post('/user/:ID', function (req, res) {
    res.json({user:true})
})

app.get('/api', function (req, res) {    
    res.send(api.listAllEndpoints(app));
}).descriptor({
    name : 'My first API documentation'
});

app.listen(8080, function () {
    console.log('Example app listening on port 8080!');
});

Example - Router instance with multiple files

server.js

vconst express = require('express');
const router1 = require('./modules/router1');
const router2 = require('./modules/router2');
const descriptor = require('express-list-endpoints-descriptor')(express);

const server = express();

//map routes
server.use('/app',router1);
server.use('/sys',router2);

//REMEMBER to invoke the listAllEndpoints or listEndpoints 
//after every route has been defined in the server object
//E.G. in the list inside endpoints /allendpoints and //endpoints are missing
var endpoints = descriptor.listEndpoints(server);

server.get('/allendpoints',(req,res)=>{
    //return all endpoints defined inside routes
    res.send(descriptor.listAllEndpoints(server));
})

server.get('/endpoints',(req,res)=>{
    //return all endpoints defined inside routes
    res.send(descriptor.listEndpoints(server));
})

//create server
var http = server.listen(8080, function () {
    console.log('TEST descriptor server listening on http://localhost:8080');            
});

modules/router1.js

const express = require('express');
var api = require('express-list-endpoints-descriptor')(express);

let router = express.Router();

router.post('/login', (req,res)=>{
    res.json({ok:true})
})
.descriptor({
    descr : 'Perform login, please look at key params for mandatory fields',
    params:[
        {username:'STRING',isMandatory:true},
        {password:'STRING',isMandatory:true}],
    isSecure:false
});

router.get('/verify',  (req,res)=>{
    res.json({ok:true});
})

router.delete('/verify',  (req,res)=>{
    res.json({ok:true});
})

router.post('/verify',  (req,res)=>{
    res.json({ok:true});
})
.descriptor({
    descr : 'decode token and gives back the session, header bearer token is needed',
    params:[
        {header:'STRING',isMandatory:true}
       ],
    isSecure:true
});

module.exports = router;

modules/router2.js

const express = require('express');
var api = require('express-list-endpoints-descriptor')(express);

let router = express.Router();


router.get('/version', (req,res)=>{
    res.json({ok:true})
})
.descriptor({
    descr : 'Get back the version of app',
    needsToken:false
});


router.get('/state',  (req,res)=>{
    res.json({ok:true});
})
.descriptor({
    descr : 'Check state of application',
    params:[
        {header:'STRING',isMandatory:true}
       ],
    needsToken:true
});

module.exports = router;

Installation

npm istall express-list-endpoints-descriptor

License

ISC

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free