Needlessly Promiscuous, Modularize!
Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

express-list-endpoints-descriptor

1.0.13 • Public • Published

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

Install

npm i express-list-endpoints-descriptor

DownloadsWeekly Downloads

63

Version

1.0.13

License

ISC

Unpacked Size

15.4 kB

Total Files

6

Last publish

Collaborators

  • avatar