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, def_ref_depth=0, param_ref=False, resp_ref=False)

Handles the creation of a swagger document from a cornice application.

CorniceSwagger.__init__(services, def_ref_depth=0, param_ref=False, resp_ref=False)
Parameters:
  • services – List of cornice services to document. You may use cornice.service.get_services() to get it.
  • def_ref_depth – How depth 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.
  • param_ref – Defines if swagger parameters should be put inline on the operation or on the parameters section and referenced by JSON pointers. Default is inline.
  • resp_ref – Defines if swagger responses should be put inline on the operation or on the responses section and referenced by JSON pointers. Default is inline.
CorniceSwagger.__call__(title, version, base_path='/', info={}, swagger={}, **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.

Generator Internals

CorniceSwagger._build_paths(ignore=['head', 'options'], default_tags=None, **kwargs)

Build the Swagger “paths” and “tags” attributes from cornice service definitions.

Parameters:
  • ignore – List of service methods that should NOT be presented on the documentation.
  • default_tags – Provide a default list of tags or a callable that takes a cornice service and returns a list of Swagger tags to be used if a tag is not provided by the view.
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)

Handles Swagger object definitions provided by cornice as colander schemas.

DefinitionHandler.__init__(ref=0)
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)

Handles swagger parameter definitions.

ParameterHandler.__init__(definition_handler=<cornice_swagger.swagger.DefinitionHandler object>, ref=False)
Parameters:
  • definition_handler – Callable that handles swagger definition schemas.
  • ref – Specifies the ref value when calling from_xxx methods.
ParameterHandler.from_schema(schema_node, validators=[])

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>, ref=False)

Handles swagger response definitions.

ResponseHandler.__init__(definition_handler=<cornice_swagger.swagger.DefinitionHandler 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>)