Swagger Framework

Swagger Framework is a module for creating Swagger Specification validated web resources using the standard Node HTTP request listener interface.

It validates and normalizes incoming requests, validates Swagger Specification, and generates the documentation endpoints.

• Documentation
• Example
• License

Documentation

• Framework
• Api
• Resource
• Operation
• Request Handler
  • sf

Declares a Framework using the Swagger API Resource Listing specification.

You should not include the apis attribute.

This acts as a container for all the API's and contains helper methods for serving HTTP resources and the documentation endpoints.

Validates resources attached to framework. This is automatically called by framework.dispatcher and framework.server.

Declares and attaches Api class.

Attaches Api instance.

Returns a function that implements the Node HTTP requestListener interface.

It also supports the Express/Connect style next argument.

Example (Express)

app.use('/api-docs', framework.docs.dispatcher());
app.use('/', framework.dispatcher());

Returns an http.Server instance which serves API's on / and the documentation endpoint on /api-docs.

Example

framework.server().listen(8000);

Declares an Api using the Swagger API Declaration specification.

You should not include the apis attribute.

Declares and attaches Resource class.

Attaches Resource instance.

Declares a Model using the Swagger Model Object specification.

Declares a Resource using the Swagger API Object specification.

You should not include the operations attribute.

Declares and attaches Operation class.

Attaches Operation instance.

Declares an Operation using the Swagger Operation Object specification.

The Operation class takes a callback that will be called when an HTTP request matches the declared API, Resource, Operation, and passes all validation checks.

This function has an Express-style signature (function(req, res, next)) where req and res are standard Node http objects (or whatever your framework passes it). next is a callback that can be called to skip the current handler, or with an Error parameter to stop execution and activate the error handler. If you're using a framework (i.e. Express) that supports next then calls will proprogate back to the framework.

This is an Accepts instance.

This is a URL object for the resource.

Example

See more in the examples directory.

var swagger = require('swagger-framework');
 
var host = '127.0.0.1';
var port = 8000;
var url = 'http://' + host + ':' + port;
 
var framework = swagger.Framework({ basePath: url });
 
var api = framework.api({
  path: '/pet',
  description: 'Manage pets',
  consumes: ['application/json'],
  produces: ['application/json'],
});
 
var resource = api.resource({ path: '/pet/{petId}' });
 
var operation = resource.operation(
  {
    method: 'GET',
    summary: 'Find pet by ID',
    notes: 'Returns a pet based on ID',
    type: 'Pet',
    nickname: 'getPetById',
    parameters: [
      {
        name: 'petId',
        description: 'ID of pet that needs to be fetched',
        required: true,
        type: 'integer',
        paramType: 'path',
        minimum: '1',
        maximum: '100000',
      },
    ],
    responseMessages: [
      {
        code: 400,
        message: 'Invalid ID supplied',
      },
      {
        code: 404,
        message: 'Pet not found',
      },
    ],
  },
  function(req, res) {
    res.sf.reply(200, {
      message: 'pet id ' + req.sf.path.petId,
    });
  }
);
 
api.model({
  id: 'Pet',
  required: ['id', 'name'],
  properties: {
    id: {
      type: 'integer',
      description: 'unique identifier for the pet',
      minimum: '0',
      maximum: '100',
    },
    name: {
      type: 'string'
    },
    photoUrls: {
      type: 'array',
      items: { type: 'string' },
    },
    status: {
      type: 'string',
      description: 'pet status in the store',
      enum: ['available', 'pending', 'sold'],
    },
  },
});
 
if (module.parent) {
  module.exports = framework;
} else {
  framework.server().listen(port, host, function(err) {
    if (err) throw err;
 
    console.log('Server started ' + url + '/');
  });
}

License

This work is licensed under the MIT License (see the LICENSE file).