bottle-swagger-2 2.0.15

Swagger Integration for Bottle

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.

This plugin is derived from Charles Blaxland’s bottle-swagger plugin: https://github.com/ampedandwired/bottle-swagger

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. Note that Bravado Core does not yet support the OpenAPI 3.0 specification, thus this plugin does not work with OpenAPI 3.0 yet.

Installation

$ pip install bottle-swagger-2

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_swagger_spec - Boolean (default True) indicating if the plugin should actually validate the Swagger spec.

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

• use_bravado_models - Boolean (default True) Should the Swagger data attached to the request be a Bravado model or just a dictionary?

• user_defined_formats - List (default None) Any user defined Swagger formats that may be fed into Bravado core.

• include_missing_properties - Boolean (default True) Should missing properties off of object in Swagger be included with None values?

• default_type_to_object - Boolean (default False) Should Swagger attributes or schemas missing the type parameter be forced to be object by default (if true) or can they be anything (if false).

• internally_derefence_refs - Boolean (default False) Should Bravado Core dereference all $refs for a performance speedup?

• ignore_undefined_api_routes - Boolean (default False) Should any routes under the given base path that don’t have a Swagger route automatically trigger a 404?

• ignore_security_definitions - Boolean (default False) Should we ignore the security requirements specified in the swagger spec? This allows you to use things like Cookie auth as an undocumented fallback without Bravado complaining.

• auto_jsonify - Boolean (default False) If the Swagger route handlers return a list or dict, should we attempt to automatically convert them to a JSON response?

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

• invalid_security_handler – (Exception -> HTTP Response) This handler is triggered when no valid forms of authentication matching the Swagger spec were in the incoming request. This is ignored if ignore_security_definitions is set to True.

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

• swagger_base_path - String (default None) Used to set and override the basePath mechanic for telling bottle what subpath to serve the API from.

• adjust_api_base_path - Boolean (default True) Adjust the basePath reported by the swagger.json. This is important if your WSGI application is running under a subpath.

• serve_swagger_schema - Boolean (default True) indicating if the Swagger schema JSON should be served

• swagger_schema_route_name - String (default None) The bottle route name to associate with the schema route. This can be set to enable determining the URL for the schema using Bottle’s get_url method.

• swagger_schema_suburl - URL (default "/swagger.json") on which to serve the Swagger schema JSON from the API subpath

• serve_swagger_ui - Boolean (default False) Should we use a built-in copy of Swagger UI to serve up docs for this API?

• swagger_ui_route_name - String (default None) The bottle route name to associate with the base URL for the swagger UI handler. This enables getting the route for the UI using bottle’s get_url method.

• swagger_ui_schema_url - String or Arity 0 callable returning a string (default None) If this is not none and the Swagger UI is turned on, this will be used to set the Swagger schema URL from which the UI draws the schema by default. If this is an arity 0 callable (i.e. a function with no arguments), this will be evaluated every time the UI is generated, which may allow the developer to dynamically select the schema URL.

• swagger_ui_suburl - String (default "/ui/") The API suburl to serve the built-in Swagger UI up at, if turned on.

• swagger_ui_validator_url - String (default None) The URL for a Swagger spec validator. By default this is None (i.e. off). This may also be an arity 0 callable that will dynamically select the validator URL when the UI is generated.

• extra_bravado_config - Dict (default None) Any additional configuration items to pass to Bravado core.

• invoke_before_spec_and_ui - Arity 0 Callable (default None) A callable function that is invoked prior to returning the UI, its assets, or the swagger schema. If the callable returns anything other than None, the result is returned instead of the schema or UI. This can be used to lock out access to the UI or schema by checking for authentication.

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