@byu-oit/byuapi
v0.0.13byuapi
DO NOT INSTALL THIS PACKAGE YET, KEEP READING...
Although this package does provide some tooling to slightly reduce the amount of code written (3 line difference), it is best to NOT INCLUDE this package as a dependency but instead to include just the dependencies your project needs.
The Tech Stack
Swagger - We use the swagger specification version 2. With swagger we define an API, including its interfaces and schemas, through a YAML or JSON file.
Sans-Server - We use sans-server, a serverless library that is similar to express although much lighter and it does not integrate directly with NodeJS' native http module. This improves development time by making it easier to write tests and tests run faster because there is no http traffic involved.
Sans-Server-Swagger - The sans-server-swagger library is a piece of sans-server middleware that performs multiple operations: 1) routing, 2) input deserialization, 3) input validation, 4) response validation, and 5) mocking. This library makes it easy to get your API up and running with only a swagger document (via mocked responses).
Sans-Server-Express or Sans-Server-Lambda are used to provide an integration to either express on an AWS EC2 or AWS EBS, or to AWS Lambda.
How To
You can copy the example directory included with this project and use it as a starter, or you can follow these steps:
Create a directory for your application to place all of your application's files.
Create a swagger file using swagger specification version 2 that represents your API.
- You can specify the controller and function each path should use by specifying the
x-controller
andoperationId
properties. See https://github.com/byu-oit/sans-server-swagger#controllers for more details.
- You can specify the controller and function each path should use by specifying the
Create the api sans-server instance:
api.js
const SansServer = require('sans-server'); const SansServerSwagger = require('sans-server-swagger'); // create a sans-server instance and export it const api = SansServer(); module.exports = api; // add swagger middleware to the sans-server instance. api.use(SansServerSwagger({ controllers: './controllers', development: true, swagger: './swagger.json' }));
Test your API.
test/api.js
const api = require('../api'); const expect = require('chai').expect; const path = require('path'); const swagger = require('sans-server-swagger'); describe('api', () => { beforeEach(() => console.log('\n')); it('response examples are valid', () => { return swagger.testSwaggerResponseExamples(path.resolve(__dirname, '../swagger.json')) .then(results => expect(results.percentage).to.equal(1)); }); it('GET /v1/pets', () => { return api.request({ method: 'GET', path: '/v1/pets' }) .then(res => { expect(res.body).to.equal('[]'); }); }); });
Create your controllers. https://github.com/byu-oit/sans-server-swagger#controllers
Create an express integration or a lambda integration.
Express Example
const api = require('./api'); const bodyParser = require('body-parser'); const express = require('express'); const expressTranslator = require('sans-server-express'); // create an express app const app = express(); // add the body parser middleware - only needed if the API will accept JSON bodies in the request app.use(bodyParser.json()); // integrate sans-server instance with express app.use(expressTranslator(api)); // start the server listening app.listen(port, function(err) { if (err) { console.error(err.stack); process.exit(1); } else { console.log('Server listening on port ' + port); } });
Lambda Example
const api = require('./api'); const lambdaTranslator = require('sans-server-aws-lambda'); exports.handler = lambdaTranslator(api);
Metadata
- Apache-2.0
- Whatever
- James Speirs
- released 10/2/2017