v0.7.1

Issues addressed:

#58, #67, #68, #71

Enhancements:

Added swagger-cors fitting

You can now use fitting/swagger-cors instead fitting/cors of and include your node_modules in fittingsDirs. Simply replace cors in your pipe with swagger-cors.

Optionally include error stack from json_error_handler

Support flag for development and integration environments: includeErrStack

openapi-error: 
  name:                 json_error_handler
  handle500Errors:      true
  includeErrStack:      true

When truthful, the automatic response-body includes the stack as well as any other enumerable attribute on the error.

Allow direct bagpipes execution as controllers

You now have a choice in how to implement controllers. The existing default acts like middleware: operationMethod(req, res, next). Alternatively, you may now chose to write your controllers as a pipe: operationMethod(ctx, next). In this case, the controller is passed with the pipeworks context, which holds a reference to .request and .response. In this model, one should generally not use ctx.response directly for responding to the client, but leave your response body on the ctx.output, the status on ctx.statusCode, and the headers on ctx.headers. The benefit is improved isolation from web-context. You don't have to run a web server to run your tests. You may just pass it a ctx and see what you find on the ctx once the callback is called. In addition, there is also an option to ask swagger-node-runner to deduce the interface from the controller's method signature. If it names 2 parameters - it's a pipe, if it names 3 parameters - it's a middleware.

This directive may be provided in few levels that cascade each other:

1. The default for the entire server - provided at config/default.yaml as swagger.bagpipes._router.controllersInterface.
2. If its more comfortable to you to express it in the swagger - you may use in your swagger.yaml the following directive on the root: x-controller-interface.
3. You may cascade the default for an entire path, suggesting that all methods of the controller that manages this path are implemented this way, using x-controller-interface on the path level.
4. Finally, you may cascade the directive per operation, using x-controller-interface on the operation level.

The legal values are one of the values: middleware, pipe, auto-detect and these correspond to the behavior described above.

Sway 1.0

The primary purpose of this release is to upgrade to Sway 1.0 which implemented several enhancements as well as fixing several outstanding issues.

PRs:
#52
#47

v0.6.16

Bug Fix: #29

v0.6.15

Bug fixes: #27, #28

Add privateTags to swagger_raw

New Features

swagger_raw

swagger_raw now looks for any objects tagged with "x-private: true" and won't include them in the served swagger. For example, you can mark a path (or operation or other object) as private in your swagger like this:

  /aPrivateAPI:
    x-private: true           # <= This object won't be included in the swagger served by swagger_raw
    x-swagger-router-controller: hello_world
    get:

This behavior can be overridden by adding a "privateTags" config option on swagger_raw to tell it which tags (it is an array) it should check to determine whether to include the object or not. See the following example modified from the standard default.yaml file for how to override this property:

    # pipe to serve swagger (endpoint is in swagger.yaml)
    swagger_raw:
      name: swagger_raw
      privateTags:
        - x-hidden      # <= use x-hidden tag instead of x-private

Note: Whatever tags you use, the values of those tags will be evaluated as "truthy" according to Javascript conventions, so the value doesn't actually to be "true" to mark an object as private. If any of the tags evaluate as "true", the object will be private.

Security handler lookup

New Features

Security Handlers

Security Handlers can now be looked up and installed automatically without having to programmatically change the configuration in app.js or elsewhere. (Note: This also allows securityHandlers to be easily installed on Sails, which wasn't easily possible prior to this.)

In order to do this, you'll need to add the "securityHandlersModule" setting for the swagger_security fitting in your config/default.yaml file and change your swagger_controllers pipe to use your configured fitting instead of the default. See the excerpt from config/default yaml below:

    _swagger_security:
      name: swagger_security
      securityHandlersModule: api/helpers/securityHandlers  # <= This is the relative path to your javascript module

    # pipe for all swagger-node controllers
    swagger_controllers:
      - onError: json_error_handler
      - cors
      - swagger_params_parser
      - _swagger_security                           # <= This references the configured security handler above
      - _swagger_validate
      - express_compatibility
      - _router

Secondly, you'll write your security handler or handlers. The javascript file you create will export an object with the names of your security handlers as your keys and the securityHandler functions as the associated values. Note that you may use either of the supported security handler styles (swagger-tools style or connect-style) and you may even use them concurrently on different handlers. For example, the module below exports a security handler that is called "api_key" in the Swagger and checks the security via a connect-style handler.

module.exports = {
  api_key: function checkApiKeySecurity(req, res, next) {
    if (req.swagger.params.name.value === 'Scott') {
      next();
    } else {
      next(new Error('access denied!'));
    }
  }
};

Response validation

New Features

Response validation

Response validation is now enabled as an event listener. No longer will turning on response validation overwrite your API responses - so now you may turn it on anytime and log the errors however you'd like without affecting your API clients. To catch validation errors, just listen for the 'responseValidationError' on the runner you create.

For example, if you have a swagger-node connect, express, restify, or hapi application, your app.js would look something like this:

SwaggerExpress.create(config, function(err, swaggerExpress) {
  if (err) { throw err; }

  // install middleware
  swaggerExpress.register(app);

  // install response validation listener (this will only be called if there actually are any errors or warnings)
  swaggerExpress.runner.on('responseValidationError', function(validationResponse, request, response) {
    // log your validationResponse here...
    console.error(validationResponse.errors);
  });

  var port = process.env.PORT || 10010;
  app.listen(port);

If you have a swagger-node sails application, the bottom of your app.js would look like this:

  sails.lift(rc('sails'), function(err, server) {

    sails.hooks['swagger-sails-hook'].runner.on('responseValidationError', function(validationResponse, request, response) {
      // log your validationResponse here...
      console.error(validationResponse.errors);
    });
  });

Notes:

• The validationResponse returned is the same format as Sway returns for its validateResponse function - (docs here).
• If there are no responseValidationError handlers, the response will not be validated, so there is no overhead.
• The validateResponse configuration property on the swagger_validator fitting is not longer used or valid.

Sway-based release

In this release, Swagger-tools has been completely replaced in this release by the new Sway library.

New Features

Configuration options:

• enforceUniqueOperationId: enforces operationId uniqueness constraint in the schema (default: false)
• startWithErrors: Start the server even if Swagger is invalid. (default: false)
• startWithWarnings: Start the server if Swagger has warnings. (default: true)

Mock mode:

• Returns examples from your Swagger based on passed-in "accept" header.
• You may now include a "_mockreturnstatus" header indicating the response code to return.

Parameter parsing:

• The swagger_params_parser fitting is now used to control parameter parsing using the body-parser and multer modules. You may override the configuration on swagger_params_parser to control these if necessary in your fittings declaration, but the defaults should work in most cases. (Note: These parsers will only parse the body if you don't otherwise set req.body before they run.) See the upgrading section below for existing projects, the default settings, and how to controlling the settings.

Security handlers:

• Security handlers may now follow either the swagger-tools security handler format or the "connect" (request, response, next) format. If you are following the connect format, however, you will be completely responsible for accessing any necessary swagger properties you need from request.swagger.operation and parameters and headers from the request.

Breaking Changes

• If you were relying on accessing swagger-tools for any reason, that will no longer work.
• Response validation does not yet exist in Sway, so is not yet supported, but will be soon.
• json_error_handler will no longer process unexpected 500 errors by default. This was deemed a potential security risk by some users in their use cases. However, if you want to pass these errors to the client as JSON, you may reenable this behavior with the "handle500Errors: true" option. See the upgrading section for details.

Upgrading

• If you are not doing your own parameter parsing, the swagger_params_parser fitting must be added to your swagger:bagpipes:swagger_controllers pipe in your config before any other swagger_* fittings. For example:

swagger_controllers:
  - onError: json_error_handler
  - cors
  - swagger_params_parser                 # <= Add this line here
  - swagger_security
  - _swagger_validate
  - express_compatibility
  - _router

Alternatively, if you need to modify the parser settings, you will need to break out the swagger_params_parser definition as follows and specify the options you wish for the parser you want to control. The values specified here are just to document the defaults for each parser:

_swagger_params_parser:                    # <= Add this definition
  name: swagger_params_parser
  jsonOptions: {}
  urlencodedOptions:
    extended: false
  multerOptions:
    inMemory: true
  textOptions:
    type: "*/*"

swagger_controllers:
  - onError: json_error_handler
  - cors
  - _swagger_params_parser                # <= Add this line here
  - swagger_security
  - _swagger_validate
  - express_compatibility
  - _router

• To enable json_error_handler formatting of unexpected errors, break out the json_error_handler definition and reference it in your pipe like so:

_json_error_handler:                       # <= Add this definition
  name: json_error_handler
  handle500Errors: true

swagger_controllers:
  - onError: _json_error_handler              # <= note name change