Here you may find information about the Cornice Swagger internals and methods that may be overwritten by applications.
cornice_swagger.swagger.
CorniceSwagger
(services=None, def_ref_depth=0, param_ref=False, resp_ref=False)¶Handles the creation of a swagger document from a cornice application.
schema_transformers
= [<function body_schema_transformer>]¶List of request schema transformers that should be applied to a request schema to make it comply with a cornice default request schema.
custom_type_converters
= {}¶Mapping for supporting custom types conversion on the default TypeConverter. Should map colander.TypeSchema to cornice_swagger.converters.schema.TypeConverter callables.
default_type_converter
= None¶Supplies a default type converter matching the interface of cornice_swagger.converters.schema.TypeConverter to be used with unknown types.
Provide a default list of tags or a callable that takes a cornice service and the method name (e.g GET) and returns a list of Swagger tags to be used if not provided by the view.
default_op_ids
= None¶Provide a callable that takes a cornice service and the method name (e.g. GET) and returns an operation Id that is used if an operation Id is not provided. Each operation Id should be unique.
default_security
= None¶Provide a default list or a callable that takes a cornice service and the method name (e.g. GET) and returns a list of OpenAPI security policies.
summary_docstrings
= False¶Enable extracting operation summaries from view docstrings.
ignore_methods
= ['HEAD', 'OPTIONS']¶List of service methods that should NOT be presented on the documentation. You may use this to remove methods that are not essential on the API documentation. Default ignores HEAD and OPTIONS.
ignore_ctypes
= []¶List of service content-types that should NOT be presented on the documentation. You may use this when a Cornice service definition has multiple view definitions for a same method, which is not supported on OpenAPI 2.0.
api_title
= ''¶Title of the OpenAPI document.
api_version
= ''¶Version of the OpenAPI document.
base_path
= '/'¶Base path of the documented API. Default is “/”.
swagger
= {'info': {}}¶Base OpenAPI document that should be merged with the extracted info from the generate call.
type_converter
¶Default cornice_swagger.converters.schema.TypeConversionDispatcher
class used for converting colander schema Types to Swagger Types.
alias of TypeConversionDispatcher
parameter_converter
¶Default cornice_swagger.converters.parameters.ParameterConversionDispatcher
class used for converting colander/cornice request schemas to Swagger Parameters.
alias of ParameterConversionDispatcher
services
= []¶List of cornice services to document. You may use cornice.service.get_services() to get it.
definitions
¶Default cornice_swagger.swagger.DefinitionHandler
class to use when
handling OpenAPI schema definitions from cornice payload schemas.
alias of DefinitionHandler
parameters
¶Default cornice_swagger.swagger.ParameterHandler
class to use when
handling OpenAPI operation parameters from cornice request schemas.
alias of ParameterHandler
responses
¶Default cornice_swagger.swagger.ResponseHandler
class to use when
handling OpenAPI responses from cornice_swagger defined responses.
alias of ResponseHandler
generate
(title=None, version=None, base_path=None, info=None, swagger=None, **kwargs)¶Generate a Swagger 2.0 documentation. Keyword arguments may be used to provide additional information to build methods as such ignores.
Parameters: |
|
---|---|
Return type: | dict Full OpenAPI/Swagger compliant specification for the application. |
CorniceSwagger.
_build_paths
()¶Build the Swagger “paths” and “tags” attributes from cornice service definitions.
CorniceSwagger.
_extract_path_from_service
(service)¶Extract path object and its parameters from service definitions.
Parameters: | service – Cornice service to extract information from. |
---|---|
Return type: | dict Path definition. |
CorniceSwagger.
_extract_operation_from_view
(view, args)¶Extract swagger operation details from colander view definitions.
Parameters: |
|
---|---|
Return type: | dict Operation definition. |
Swagger definitions and parameters are handled in separate classes. You may overwrite those if you want to change the converters behaviour.
cornice_swagger.swagger.
DefinitionHandler
(ref=0, type_converter=<cornice_swagger.converters.schema.TypeConversionDispatcher object>)¶Handles Swagger object definitions provided by cornice as colander schemas.
DefinitionHandler.
__init__
(ref=0, type_converter=<cornice_swagger.converters.schema.TypeConversionDispatcher object>)¶Parameters: | ref – The depth that should be used by self.ref when calling self.from_schema. |
---|
DefinitionHandler.
from_schema
(schema_node, base_name=None)¶Creates a Swagger definition from a colander schema.
Parameters: |
|
---|---|
Return type: | dict Swagger schema. |
DefinitionHandler.
_ref_recursive
(schema, depth, base_name=None)¶Dismantle nested swagger schemas into several definitions using JSON pointers. Note: This can be dangerous since definition titles must be unique.
Parameters: |
|
---|---|
Return type: | dict JSON pointer to the root definition schema, or the original definition if depth is zero. |
cornice_swagger.swagger.
ParameterHandler
(definition_handler=<cornice_swagger.swagger.DefinitionHandler object>, ref=False, type_converter=<cornice_swagger.converters.schema.TypeConversionDispatcher object>, parameter_converter=<cornice_swagger.converters.parameters.ParameterConversionDispatcher object>)¶Handles swagger parameter definitions.
ParameterHandler.
__init__
(definition_handler=<cornice_swagger.swagger.DefinitionHandler object>, ref=False, type_converter=<cornice_swagger.converters.schema.TypeConversionDispatcher object>, parameter_converter=<cornice_swagger.converters.parameters.ParameterConversionDispatcher object>)¶Parameters: |
|
---|
ParameterHandler.
from_schema
(schema_node)¶Creates a list of Swagger params from a colander request schema.
Parameters: |
|
---|---|
Return type: | list List of Swagger parameters. |
ParameterHandler.
from_path
(path)¶Create a list of Swagger path params from a cornice service path.
Return type: | list |
---|
ParameterHandler.
_ref
(param, base_name=None)¶Store a parameter schema and return a reference to it.
Parameters: |
|
---|---|
Return type: | dict JSON pointer to the original parameter definition. |
cornice_swagger.swagger.
ResponseHandler
(definition_handler=<cornice_swagger.swagger.DefinitionHandler object>, type_converter=<cornice_swagger.converters.schema.TypeConversionDispatcher object>, ref=False)¶Handles swagger response definitions.
ResponseHandler.
__init__
(definition_handler=<cornice_swagger.swagger.DefinitionHandler object>, type_converter=<cornice_swagger.converters.schema.TypeConversionDispatcher object>, ref=False)¶Parameters: |
|
---|
ResponseHandler.
from_schema_mapping
(schema_mapping)¶Creates a Swagger response object from a dict of response schemas.
Parameters: | schema_mapping – Dict with entries matching {status_code: response_schema} . |
---|---|
Return type: | dict Response schema. |
ResponseHandler.
_ref
(resp, base_name=None)¶Store a response schema and return a reference to it.
Parameters: |
|
---|---|
Return type: | dict JSON pointer to the original response definition. |
You may use the cornice_swagger.converters
submodule to access the colander
to swagger request and schema converters. These may be also used without
cornice_swagger
generators.
This module handles the conversion between colander object schemas and swagger object schemas.
cornice_swagger.converters.
convert_schema
(schema_node)¶cornice_swagger.converters.
convert_parameter
(location, schema_node, definition_handler=<function convert_schema>)¶