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, pyramid_registry=None)¶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.
type_converter
¶alias of cornice_swagger.converters.schema.TypeConversionDispatcher
parameter_converter
¶alias of cornice_swagger.converters.parameters.ParameterConversionDispatcher
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.
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 |
Returns: | Full OpenAPI/Swagger compliant specification for the application. |
cornice_swagger.
cornice_enable_openapi_view
(config, api_path='/api-explorer/swagger.json', permission='__no_permission_required__', route_factory=None, **kwargs)¶Parameters: |
|
---|
This registers and configures the view that serves api definitions
cornice_swagger.
cornice_enable_openapi_explorer
(config, api_explorer_path='/api-explorer', permission='__no_permission_required__', route_factory=None, **kwargs)¶Parameters: |
|
---|
This registers and configures the view that serves api explorer
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 |
Returns: | Path definition. |
CorniceSwagger.
_extract_operation_from_view
(view, args)¶Extract swagger operation details from colander view definitions.
Parameters: |
|
---|---|
Return type: | dict |
Returns: | 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 |
Returns: | 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 |
Returns: | 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 |
Returns: | 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 |
Returns: | 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 |
Returns: | Response schema. |
ResponseHandler.
_ref
(resp, base_name=None)¶Store a response schema and return a reference to it.
Parameters: |
|
---|---|
Return type: | dict |
Returns: | 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>)¶