Bottle Swagger Plugin

About

This project is a Bottle plugin for working with Swagger. Bottle is a Python web framework. Swagger (OpenAPI) is a standard for defining REST APIs.

So if you are serving a REST API with Bottle, and you have a defined a Swagger schema for that API, this plugin can:

Validate incoming requests and outgoing responses against the swagger schema
Return appropriate error responses on validation failures
Serve your swagger schema via Bottle (for use in Swagger UI for example)

Requirements

Python >= 2.7
Bottle >= 0.12
Swagger specification >= 2.0

This project relies on bravado-core to perform the swagger schema validation, so any version of the Swagger spec supported by that project is also supported by this plugin.

Installation

$ pip install bottle-swagger

Usage

See the "example" directory for a working example of using this plugin.

The simplest usage is:

import bottle

swagger_def = _load_swagger_def()
bottle.install(SwaggerPlugin(swagger_def))

Where "_load_swagger_def" returns a dict representing your swagger specification (loaded from a yaml file, for example).

There are a number of arguments that you can pass to the plugin constructor:

validate_requests - Boolean (default True) indicating if incoming requests should be validated or not
validate_responses - Boolean (default True) indicating if outgoing responses should be validated or not
ignore_undefined_routes - Boolean (default False) indicating if undefined routes (that is, routes not defined in the swagger spec) should be passed on ("True") or return a 404 ("False")
invalid_request_handler - Callback called when request validation has failed. Default behaviour is to return a "400 Bad Request" response.
invalid_response_handler - Callback called when response validation has failed. Default behaviour is to return a "500 Server Error" response.
swagger_op_not_found_handler - Callback called when no swagger operation matching the request was found in the swagger schema. Default behaviour is to return a "404 Not Found" response.
exception_handler=_server_error_handler - Callback called when an exception is thrown by downstream handlers (including exceptions thrown by your code). Default behaviour is to return a "500 Server Error" response.
serve_swagger_schema - Boolean (default True) indicating if the Swagger schema JSON should be served
swagger_schema_url - URL (default /swagger.json) on which to serve the Swagger schema JSON

All the callbacks above receive a single parameter representing the Exception that was raised, or in the case of swagger_op_not_found_handler the Route that was not found. They should all return a Bottle Response object.

Contributing

Development happens in the bottle-swagger GitHub respository. Pull requests (with accompanying unit tests), feature suggestions and bug reports are welcome.

Use "tox" to run the unit tests:

$ tox