samkhawase / swagger-suite

The complete suite of Swagger tools, packaged together seamlessly and ready to use.

Swagger-Suite

The complete suite of Swagger tools, packaged together seamlessly and ready to use.

Edit your API spec, mock it, test it, and document it, all from one app.

Features

• Experience "design-first" API development - Design your REST API spec in Swagger Editor, and Swagger-Suite will make sure your documentation, tests, and mocks are all kept in sync with your design.

• Use your favorite code editor - Prefer using Sublime Text or some other editor instead of the WYSIWYG tool? That's fine. Swagger-Suite will still detect your changes and keep the docs, tests, and mocks in sync with your spec.

• Don't waste time writing boilerplate code - The built-in Swagger-Server automatically and intelligently mocks your API in real time as you design it. So you can instantly interact with your API and get valid responses back without writing any code.

• Simple extensibility via Express.js - Suppliment Swagger-Server's mocks with your own custom logic, or replace the mocks entirely with your real API implementation. It's as easy as function(req, res, next)

• Test your API in any browser - Swagger-Suite includes Swagger-UI, which lets you easily test your API in any browser.

• Test your API in Postman - If you prefer to use Postman to test your REST APIs, then Swagger-Suite's got you covered. It exposes your API as a Postman collection.

• Beautiful API Documentation - Your API is only as good as its documentation, and Swagger Editor makes it simple to provide clear, comprehensive, and beautiful HTML docs.

Supported Swagger Versions

• 2.0

Installation

Prerequisites

• Node.js - This one probably goes without saying, but...

• Bower - Swagger-Suite uses Bower to manage all of its frontend packages.

Install Steps

Once you have the prerequisites installed, run the following commands.

npm install swagger-suite

cd node_modules/swagger-suite
bower install

The cd and bower install commands are necessry to install frontend packages like Swagger-UI and Swagger Editor. These frontend packages are not included in Swagger-Suite's NPM package so that they can be updated independently.

Running the samples

Swagger-Suite comes with two sample apps: the ubiquitous "Swagger Petstore" is a simple example, and the "User Manager" demonstrates more advanced concepts. To run the petstore sample, just cd into the node_modules/swagger-suite folder and run the following command:

cd node_modules/swagger-suite
npm run petstore

Or, on Windows:

cd node_modules\swagger-suite
npm run petstore-windows

Similarly, to run the "User Manager" sample insead, run:

cd node_modules/swagger-suite
npm run users

Or, on Windows:

cd node_modules\swagger-suite
npm run users-windows

Note: All of the above commands run the sample apps in DEBUG mode, which produces a lot of output in the console window.

Now open your browser

Both of the sample apps are configured to run at http://localhost:3000, so open your browser and go check 'em out!

Walkthrough

TODO

Contributing

I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request. Use JSHint to make sure your code passes muster. (see .jshintrc).

Here are some things currently on the to-do list:

• Unit tests - Need lots of 'em! Planning to use Mocha and Chai

• Gulp build script - Automate SASS, JSHint, and unit tests

• Postman support - This is coming very soon.

License

Swagger-Suite is 100% free and open-source, under the MIT license. Parts of this software were created by third-parties and are subject to other software licenses. Click here for details