Swagger Integration for Bottle
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)
- 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.
$ pip install bottle-swagger-2
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_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_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.
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.
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:
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size bottle_swagger_2-2.0.10-py2.py3-none-any.whl (3.0 MB)||File type Wheel||Python version py2.py3||Upload date||Hashes View|
|Filename, size bottle-swagger-2-2.0.10.tar.gz (2.5 MB)||File type Source||Python version None||Upload date||Hashes View|
Hashes for bottle_swagger_2-2.0.10-py2.py3-none-any.whl