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 object is attached to the req and res instances. It is used to pass state between middleware and includes helper functions.

This is an Accepts instance.

This is an object of body values. It has already been validated and normalized against the Swagger specification.

Additional values are discarded unless the removeBody option is set to false.

This is an object of form values. It has already been validated and normalized against the Swagger specification.

Additional values are discarded unless the removeForm option is set to false.

This is an object of headers. It has already been validated and normalized against the Swagger specification.

Additional headers are discarded unless the removeHeader option is set to false.

This is an object of path segments. It has already been validated and normalized against the Swagger specification.

This formats and replies to the HTTP request.

statusCode should be a numeric HTTP response code (defaults to 200).

body should be the response content.

This formats and replies to the HTTP request.

statusCode should be a numeric HTTP response code (defaults to 500).

err should be an instance of Error. If err.statusCode is defined it will be used as the return status code. If err.expose is truthy then err.toJSON() (if defined) or err.message will be set as the response body.

This is a callback that you can attach to the sf attribute to format reply calls.

reply will be an object that contains statusCode, body, and args. statusCode and body are the response attributes that reply interpreted from the caller. args is an array of the actual arguments.

responseMessage should either return an object with statusCode and body, or a falsy value and handle the response itself.

This is an object of query parameters. It has already been validated and normalized against the Swagger specification.

Additional query parameters are discarded unless the removeQuery option is set to false.

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).