Swagger Microservice

WARNING: project is in alpha and undergoing heavy development - it is NOT production ready

The Swagger-Microservice project is a highly opinionated REST framework that relies on a document-first approach to API design based on Swagger (aka OpenAPI) 2.0. If an API's endpoints contain basic business logic, a fully functional and scalable REST API is possible without writing a single line of code other than the Swagger definition. However, custom logic and code can be injected into the request-response pipeline as necessary.

Features

• Supports the design-first API approach

  Design fast, fail faster. In today's agile development environment, it is vital to figure out what works and what doesn't as quickly as possible. Instead of building out the code for a complex API, then building out the clients to test it, the Swagger Microservice will allow developers to rapidly design a working API using only a Swagger definition file. The Swagger specification can also be used to generate client code for a variety of languages. This frees the developer to focus on the front-end customer facing experience.

• Mock Mode

  Design, prototype and test your API immediately. Mock data can either be provided via examples in the Swagger definition or it can be autogenerated on the fly based on the Swagger schema.

• In-Memory Datastore Mode

  The framework is designed to accept any datastore that adheres to the required function contracts. However, an in-memory datastore is provided to get an API running immediately. Data won't be persisted, but developers can immediately start testing their API's functionality and later replace the memory data store with one that provides persistence (ie: mySql,Postgres, DynamoDb, DocumentDb, etc.).

• Persisted Datastore Mode

  The framework is designed to accept any data store that adheres to the required functional contracts. The framework provides an in-memory datastore to power an API during development testing. This datastore can then be swapped out in QA or production for a fully functional data store with one that provides persistence (ie: mySql,Postgres, DynamoDb, DocumentDb, etc.).

• Functionaly Separated Data Stores for Scalability

  As APIs scale, it us often a requirement to break out the backing database into read-write/read-only or eventually consistent architectures. Our framework is ready from the start with the ability to call separate READ, QUERY and WRITE data stores. For example, the primary WRITE data store could be a RabbitMQ queue that feeds into a (READ) relational Postgres database as well as a (FIND) SOLR engine. Or the architecture may call for a primary MySql as the WRITE and READ data stores and a set of read-only secondaries as the FIND data store. Or the READ, WRITE and QUERY data stores are one monolithic MongoDb. The Swagger Microservice architecture can handle any of these approaches and more.

• Swagger 2.0

  Use either a JSON or YAML specification file to drive your API.

• Support traditional HTTP REST methods

  GET, POST, PUT, PATCH, DELETE are supported.

• Support JSON, XML and CSV request and responses

  Though the API world is moving to JSON over HTTP, we support XML and CSV out of the box as well with other formats to come.

Quick Start

Install the package into your project

npm install --save swagger-microservice

The simplest way to get started is to use the internal in-memory datastore or to configure the service to generate mock data.

Mock Data

Generates mock data for every endpoint in the API. The mock server relies on the excellent json-schema-faker library package.

Uses the examples parameter of the swagger response object. If that is not defined, will autogenerate data based on the response schema.

    'use strict';
    
    const Microservice  = require('swagger-microservice'),
          swagger       = require('./swagger.json'),
          express       = require('express'),
          app           = new express();
          
    let serverPort = 8080;
    let server = new Microservice();
    
    server.initialize(swagger, app, {isMock: true }, function(err) {
        server.startServer(serverPort, function(err) {
            if(err) {
                console.log("Error", err);
            }
            else {
                console.log("server started");
            }
        });
    });

A basic mock implementation using the standard Petstore Swagger definition can be found at /examples/mock. To run it:

node ./examples/mock/index.js

Then make a request to localhost:8080/v1/pets. If all goes well, an array of randomly generated pets should appear.

The sample can also be found as a stand-alone node.js project at https://gitlab.com/apitheory/swagger-microservice-example-mock. It includes a Dockerfile which allows the mock server to be run in a docker container.

In-Memory Datastore

The in-memory datastore option allows endpoints to be interacted with to a deeper degree than the mock option. Loki.js is used as the underlying datastore. Note that the only part of the script that changes from the mock implementation, is the removal of the option isMock:true.

    'use strict';
    
    const Microservice  = require('swagger-microservice'),
          swagger       = require('./swagger.json'),
          express       = require('express'),
          app           = new express();
          
    let serverPort = 8081;
    let server = new Microservice();
    server.initialize(swagger, app, function(err) {
        server.startServer(serverPort, function(err) {
            if(err) {
                console.log("Error", err);
            }
            else {
                console.log("server started");
            }
        });
    });

A basic implementation using the in-memory database and the standard Petstore Swagger definition can be found at /examples/in-memory. To run it:

node ./examples/in-memory/index.js

Then make a request to localhost:8081/v1/pets. If all goes well, an array of randomly generated pets should appear.

Contributions

Create your own fork apitheory/swagger-microservice, make your changes (please see our contribution guidelines ), then submit a pull request.

Documentation

• FAQ
• Contribution Guidelines
• Data Adapter Docs

External Project Call Outs

The project relies heavily on these open source projects:

• swagger-express-middleware: Our project would not exist without the wonderful swagger-express-middleware package.
• express
• json-schema-faker: The core of our mock server implementation.
• loki.js: Used to provide in-memory datastore.

License

The Swagger Microservice is licensed under the MIT license. Feel free to go crazy and use it in whatever way you want.