express-api

Express-api is an API framework based on Swagger.

Express-api uses CSON, JSON or YAML files to expose your apis using the
eapiger specs. Express-eapi reloads schemas in development facilitating schema
creation.

DO NOT USE, WIP! Documentation is inaccurate.

Using

Install the library

npm install express-api

Create resource listings schema and resource schema files in a common
directory, eg public/api/docs. Here are the official examples

- petstore resource listing
- petstore resource

Implement your resource API. NOTE, the name of your resoure methods must match
the nickname property in the schema operations

``
//// pet.json
apis: [{
path: "/pet/{petId}",
operations: [{
summary: "Find pet by ID",
nickname: "getPetById",
}]
}]
`

`
//// resource/pet.js
exports.getPetById = function(req, res) {
}
`

Wire it all up

`
var express = require('express');
var app = express();
var Swag = require('express-eapi');

// create routers for API and docs
var apiRouter = express.Router();
var docsRouter = epxress.Router();
app.use('/api', apiRouter);
app.use('/api/api-docs', docsRouter);

var eapi = new Swag({
apiRouter: apiRouter,
docsRouter: docsRouter,
docsDir: 'public/api/docs',
extname: '.json'
});

eapi
.addApi('pet.json', require('./resources/pet.js'))
.addApi('user.json', require('./resources/user.js'))
.configureDocs('index.json', 'http://localhost:8000/api');

app.listen(3000);
`

Browser your json schemas at http://localhost:3000/api/api-docs or
through the eapiger UI.

Middleware

The primary reason for creating express-api is the lack of support for
plain middleware in other frameworks.

The implementation method can either be a function or array of functions.

exports.getPetById = function(req, res, next) { ... };

exports.getPetById = [
validationMiddleware({ body: {id: joi.integer()}}),
function(req, res, next) { ... };
];

That can be a bit tedious. Express-api can use middleware as plugins. Let's
create one.

function validate(req, res, next) {
// get the spec for the current operation
var spec = req.__eapiger.operation;
var params = spec.parameters;
params.forEach(function(param) {
if (param.required && param.paramType === 'path') {
if (!req.params[param.name]) res.send(400, 'Require argument missing' + param.name);
}
});

next();
}

To use it

eapi
.use(validate)
.addApi('pet.json', require('./resources/pet.js'))

The position matters. All middleware used before addApi` are applied before
a operation method in the pipeline. Post filters look like this.

eapi
.addApi('pet.json', require('./resources/pet.js'))
.use(normalizeResult);