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