mozilla

Cornice Swagger API

Here you may find information about the Cornice Swagger internals and methods that may be overwritten by applications.

Basic Generator

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

default_tags = None

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:
  • title – The name presented on the swagger document.
  • version – The version of the API presented on the swagger document.
  • base_path – The path that all requests to the API must refer to.
  • info – Swagger info field.
  • swagger – Extra fields that should be provided on the swagger documentation.
Return type:

dict Full OpenAPI/Swagger compliant specification for the application.

Generator Internals

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:
  • view – View to extract information from.
  • args – Arguments from the view decorator.
Return type:

dict Operation definition.

Section Handlers

Swagger definitions and parameters are handled in separate classes. You may overwrite those if you want to change the converters behaviour.

class 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:
  • schema_node – Colander schema to be transformed into a Swagger definition.
  • base_name – Schema alternative title.
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:
  • schema – Base swagger schema.
  • depth – How many levels of the swagger object schemas should be split into swaggger definitions with JSON pointers. Default (0) is no split. You may use negative values to split everything.
  • base_name – If schema doesn’t have a name, the caller may provide it to be used as reference.
Return type:

dict JSON pointer to the root definition schema, or the original definition if depth is zero.

class 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:
  • definition_handler – Callable that handles swagger definition schemas.
  • ref – Specifies the ref value when calling from_xxx methods.
ParameterHandler.from_schema(schema_node)

Creates a list of Swagger params from a colander request schema.

Parameters:
  • schema_node – Request schema to be transformed into Swagger.
  • validators – Validators used in colander with the schema.
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:
  • schema – Swagger parameter definition.
  • base_name – Name that should be used for the reference.
Return type:

dict JSON pointer to the original parameter definition.

class 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:
  • definition_handler – Callable that handles swagger definition schemas.
  • ref – Specifies the ref value when calling from_xxx methods.
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:
  • schema – Swagger response definition.
  • base_name – Name that should be used for the reference.
Return type:

dict JSON pointer to the original response definition.

Colander converters

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>)