Swagger Server

Get your REST API up-and-running FAST with Swagger and Express

Features

• Supports Swagger 2.0 specs in JSON or YAML
  Swagger Express Middleware uses Swagger-Parser to parse, validate, and dereference Swagger files. You can even split your spec into multiple different files using $ref pointers.

• Build your API in real-time
  Swagger Server automatically watches reloads your files as you work on them. No need to restart the server. Test your code changes in real time!

• Intelligent Mocks
  Swagger Server automatically provides mock implementations for every operation in your API definition, complete with data persistence. So you can have a fully-functional mock API with zero code. You can even extend Swagger Server's mocks with your own logic.

• Powered by Express
  Implement your API with all the power and simplicity of Express.js. Use any third-party Express middleware, or write your own. It's as easy as function(req, res, next)

• Write your API however you want
  Write your Swagger API in JSON or YAML. Put it all in one big file, or separate it out into as many different files and folders as you want. You can even use a combination of JSON and YAML files.

• Write your code however you want
  Swagger Server can automatically detect your handlers based on folder structure and naming convention, or you can explicitly specify your handlers in code. Or, if you're already comfortable with Express.js methods like use, all, route, get/post/delete/etc., then you can use those directly.

Installation

Swagger Server requires Node.js, so install that first. Then install Swagger Server using the following npm command:

npm install swagger-server

Usage

Express-Compatible API

Swagger Server is built on top of Express.js and can be used as a 100% compatible drop-in replacement for Expess in any app. Just use require("swagger-server") instead of require("express") and pass the path to your Swagger file when creating your Application object.

var swaggerServer = require('swagger-server');
var app = swaggerServer('MyRestApi.yaml');

// GET /users
app.get('/users', function(req, res, next) {
    res.send(myListOfUsers);
});

// Start listening on port 8000
app.listen(8000, function() {
  console.log('Your REST API is now running at http://localhost:8000');
});

Swagger Server API

Swagger Server also exposes some additional classes, events, and methods on top of Express's functionality. You can access these additional APIs by instantiating a Swagger.Server object, which has an API very similar to Express's Application object:

var swagger = require('swagger-server');
var server = new swagger.Server();

// Parse the Swagger file
server.parse('PetStore.yaml');

// GET /users
server.get(function(req, res, next) {
  res.send(myListOfUsers);
});

// Start listening on port 8000
server.listen(8000, function() {
  console.log('Your REST API is now running at http://localhost:8000');
});

Running the samples

Swagger Server comes three samples that use the Swagger Pet Store API.

Sample 1

This sample demonstrates the most simplistic usage of Swagger Server. It simply loads the PetStore.yaml file and starts the server. There's no custom code at all.

• Source Code
• Walkthrough

Sample 2

This sample demonstrates a few more advanced features, such as setting a few options, loading mock data, and adding custom middleware logic.

• Source Code
• Walkthrough

Sample 3

This sample demonstrates Swagger Server's automatic module loading, as well as more advanced custom middleware logic.

// NOTE: This sample is still a work-in-progress

Contributing

I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request.

Building/Testing

To build/test the project locally on your computer:

1. Clone this repo
   git clone https://github.com/BigstickCarpet/swagger-server.git

2. Install all dependencies (including dev dependencies)
   npm install

3. Run the build script
   npm run build

4. Run the unit tests
   npm test (tests + code coverage)
   npm run mocha (just the tests)

5. Run the sample app
   npm start

License

Swagger Server is 100% free and open-source, under the MIT license. Use it however you want.