def param(name,
type=str,
location='query',
description=None,
format=None,
required=False,
default=None):
'''
A decorator to specify one of the expected parameters
:param str name: the parameter name
:param str description: a small description
:param str location: the parameter location `(query|header|formData|body|cookie)`
'''
return doc(
params={
name:
not_none({
'in': location,
'type': type,
'format': format,
'default': default,
'required': True if required else None,
'description': description
})
})
def create_schema(type='object',
default=None,
format=None,
title=None,
description=None,
readonly=None,
example=None,
**kwargs):
required = kwargs.pop('required', False)
discriminator = kwargs.pop('discriminator', None)
schema = not_none({
'type': type,
'format': format,
'title': title,
'description': description,
'readOnly': readonly,
'default': _eval(default),
'example': example,
**kwargs
})
return immutable({
'__schema__': schema,
'schema': lambda: schema,
'required': required,
'discriminator': discriminator,
'description': description
})
def expected_params(apidoc):
params = OrderedDict()
for model, description in apidoc.get('expect', []):
if isinstance(model, Model):
params['payload'] = not_none({
'name': 'payload',
'required': True,
'in': 'body',
'schema': ref(model)
})
continue
params['payload'] = not_none({
'name': 'payload',
'required': True,
'in': 'body',
'schema': ref(model),
'description': description
})
return params
def create_header_object(header):
if isinstance(header, str):
header = {'description': header}
typedef = header.get('type', 'string')
if isinstance(typedef, Hashable) and typedef in PY_TYPES:
header['type'] = PY_TYPES[typedef]
elif isinstance(
typedef,
(list, tuple)) and len(typedef) == 1 and typedef[0] in PY_TYPES:
header['type'] = 'array'
header['items'] = {'type': PY_TYPES[typedef[0]]}
elif hasattr(typedef, '__schema__'):
header.update(typedef.__schema__)
else:
header['type'] = typedef
return not_none(header)
def _schema(self):
properties = {}
required = set()
discriminator = None
for name, field in self.attributes.items():
properties[name] = field.__schema__
if field.required:
required.add(name)
if getattr(field, 'discriminator', False):
discriminator = name
return not_none({
'required': sorted(list(required)) or None,
'properties': properties,
'discriminator': discriminator,
'type': 'object',
})
def serialize_operation(apidoc):
parameters = parameters_for(apidoc)
operation = {
'responses': responses_for(apidoc) or None,
# 'summary': 'TODO-ray parse docstirng from here', # doc[method]['docstring']['summary'],
'description': apidoc.get('description') or None,
'operationId': apidoc.get('name'),
'parameters': parameters,
'security': security_for(apidoc),
'consumes': get_operation_consumes(parameters),
'produces': get_operation_produces(apidoc),
'tags': get_operation_namespace(apidoc),
'deprecated': True if apidoc.get('deprecated', False) else None
}
operation.update(vendor_fields(apidoc))
return not_none(operation)
def create_openapi_spec_dict(metadata, handlers):
'''
Output the specification as a serializable ``dict``.
:returns: the full Swagger specification in a serializable format
:rtype: dict
'''
paths = build_paths(handlers)
models = find_models(handlers)
return not_none({
'swagger': '2.0',
'basePath': parse_base_path(metadata.base_path),
'paths': not_none_sorted(paths),
'info': build_infos(metadata),
'produces': metadata.representations,
'consumes': ['application/json'],
'securityDefinitions': metadata.authorizations or None,
'security': security_requirements(metadata.security) or None,
'tags': extract_tags(metadata, handlers),
'definitions': serialize_definitions(models) or None,
'host': metadata.host,
})
def namespace(name, description=None):
'''A decorator that groups the decorated handler function in a namespace'''
return doc(namespace=not_none({'name': name, 'description': description}))