{swagger-express}

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. View demo.

{swagger-express} is a simple and clean solution to integrate swagger with express.

Installation

$ npm install -g swagger-express

Quick Start

Configure {swagger-express} as express middleware.

apiVersion -> Your api version.

swaggerVersion -> Swagger version.

swaggerUI -> Where is your swagger-ui?

swaggerURL -> Path to use for swagger ui web interface.

swaggerJSON -> Path to use for swagger ui JSON.

basePath -> The basePath for swagger.js

apis -> Define your api array.

middleware -> Function before response.

var swagger = require('swagger-express');

app.configure(function(){
  ...
  app.use(swagger.init(app, {
    apiVersion: '1.0',
    swaggerVersion: '1.0',
    swaggerURL: '/swagger',
    swaggerJSON: '/api-docs.json',
    swaggerUI: './public/swagger/',
    basePath: 'http://localhost:3000',
    apis: ['./api.js', './api.yml'],
    middleware: function(req, res){}
  }));
  app.use(app.router);
  ...
});

Read from jsdoc

Example 'api.js'

1
2/**
3 * @swagger
4 * resourcePath: /api
5 * description: All about API
6 */
7
8/**
9 * @swagger
10 * path: /login
11 * operations:
12 *   -  httpMethod: POST
13 *      summary: Login with username and password
14 *      notes: Returns a user based on username
15 *      responseClass: User
16 *      nickname: login
17 *      consumes: 
18 *        - text/html
19 *      parameters:
20 *        - name: username
21 *          description: Your username
22 *          paramType: query
23 *          required: true
24 *          dataType: string
25 *        - name: password
26 *          description: Your password
27 *          paramType: query
28 *          required: true
29 *          dataType: string
30 */
31exports.login = function (req, res) {
32  var user = {};
33  user.username = req.param('username');
34  user.password = req.param('password');
35  res.json(user);
36}
37
38/**
39 * @swagger
40 * models:
41 *   User:
42 *     id: User
43 *     properties:
44 *       username:
45 *         type: String
46 *       password:
47 *         type: String    
48 */

Read from yaml file

Example 'api.yml'

1resourcePath: /api
2description: All about API
3apis: 
4
5- path: /login
6  operations:
7
8  - httpMethod: POST
9    summary: Login with username and password
10    notes: Returns a user based on username
11    responseClass: User
12    nickname: login
13    consumes: 
14      - text/html
15    parameters:
16
17    - name: username
18      dataType: string
19      paramType: query
20      required: true
21      description: Your username
22
23    - name: password
24      dataType: string
25      paramType: query
26      required: true
27      description: Your password
28
29models:
30    User:
31      id: User
32      properties:
33        username:
34          type: String
35        password:
36          type: String    

Read from jsdoc

Example 'api.coffee'

1
2###
3 * @swagger
4 * resourcePath: /api
5 * description: All about API
6###
7
8###
9 * @swagger
10 * path: /login
11 * operations:
12 *   -  httpMethod: POST
13 *      summary: Login with username and password
14 *      notes: Returns a user based on username
15 *      responseClass: User
16 *      nickname: login
17 *      consumes:
18 *        - text/html
19 *      parameters:
20 *        - name: username
21 *          description: Your username
22 *          paramType: query
23 *          required: true
24 *          dataType: string
25 *        - name: password
26 *          description: Your password
27 *          paramType: query
28 *          required: true
29 *          dataType: string
30###
31
32###
33 * @swagger
34 * models:
35 *   User:
36 *     id: User
37 *     properties:
38 *       username:
39 *         type: String
40 *       password:
41 *         type: String
42###

Examples

Clone the {swagger-express} repo, then install the dev dependencies:

$ git clone git://github.com/fliptoo/swagger-express.git --depth 1
$ cd swagger-express
$ npm install

and run the example:

$ cd example
$ node app.js

Credits

• Express
• swagger-jack

License

(The MIT License)

Copyright (c) 2013 Fliptoo <fliptoo.studio@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.