scorpil/swagger-server

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

Swagger Server

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

v1.0.0 Alpha Notice !

We are currently working on the v1.0.0 release, which is a complete rewrite and is not backward-compatible with v0.0.x. To continue using the current stable version of Swagger Server, use npm install [email protected] To start using the alpha version of Swagger Server 1.0, use npm install swagger-server@latest. Please be aware that the alpha version may still undergo some API changes before being released. It's not finished yet, and some of the samples don't work yet. But feel free to try it out and provide feedback.

Features

• Supports Swagger 2.0 specs in JSON or YAML
  Swagger Server 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@latest

Usage

Express 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 project. 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 in addition to Express's API. 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('/users', 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');
});

Samples & Walkthroughs

There are several complete, well-documented samples available for Swagger Server. Install them using npm, then see the Walkthrough for instructions.

npm install swagger-server-samples

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)

License

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