def get_ref_schema(base, schema):
"""Create a JSONSchema object that is a reference to `schema`
:param schema:
:param base: base string for references, e.g. "#/definitions"
:return:
"""
ref = {sw.ref: create_ref(base, get_swagger_title(schema))}
return ref if not schema.many else {sw.type_: sw.array, sw.items: ref}
def _get_response_description(schema):
"""
Retrieves a response description from a Marshmallow schema.
This is a required field, so we _have_ to give something back.
:param marshmallow.Schema schema:
:rtype: str
"""
if schema.__doc__:
return schema.__doc__
else:
return get_swagger_title(schema)
def _get_paths(self, paths, default_headers_schema):
path_definitions = {}
for path, methods in paths.items():
swagger_path, path_args = _format_path_for_swagger(path)
# Different Flask paths might correspond to the same Swagger path
# because of Flask URL path converters. In this case, let's just
# work off the same path definitions.
if swagger_path in path_definitions:
path_definition = path_definitions[swagger_path]
else:
path_definitions[swagger_path] = path_definition = {}
if path_args:
path_params = [
{
sw.name: path_arg.name,
sw.required: True,
sw.in_: sw.path,
sw.type_: self.flask_converters_to_swagger_types[path_arg.type]
}
for path_arg in path_args
]
# We have to check for an ugly case here. If different Flask
# paths that map to the same Swagger path use different URL
# converters for the same parameter, we have a problem. Let's
# just throw an error in this case.
if sw.parameters in path_definition:
_verify_parameters_are_the_same(
path_definition[sw.parameters],
path_params
)
path_definition[sw.parameters] = path_params
for method, d in methods.items():
responses_definition = {
sw.default: {
sw.description: _get_response_description(self.default_response_schema),
sw.schema: {
sw.ref: _get_ref(get_swagger_title(self.default_response_schema))
}
}
}
if d.marshal_schema:
for status_code, schema in d.marshal_schema.items():
if schema is not None:
response_definition = {
sw.description: _get_response_description(schema),
sw.schema: {sw.ref: _get_ref(get_swagger_title(schema))}
}
responses_definition[str(status_code)] = response_definition
else:
responses_definition[str(status_code)] = {
sw.description: 'No response body.'
}
parameters_definition = []
if d.query_string_schema:
parameters_definition.extend(
_convert_jsonschema_to_list_of_parameters(
self._query_string_converter(d.query_string_schema),
in_=sw.query
)
)
if d.request_body_schema:
schema = d.request_body_schema
parameters_definition.append({
sw.name: schema.__class__.__name__,
sw.in_: sw.body,
sw.required: True,
sw.schema: {sw.ref: _get_ref(get_swagger_title(schema))}
})
if d.headers_schema is USE_DEFAULT and default_headers_schema:
parameters_definition.extend(
_convert_jsonschema_to_list_of_parameters(
self._headers_converter(default_headers_schema),
in_=sw.header
)
)
elif d.headers_schema is not USE_DEFAULT and d.headers_schema is not None:
parameters_definition.extend(
_convert_jsonschema_to_list_of_parameters(
self._headers_converter(d.headers_schema),
in_=sw.header
)
)
method_lower = method.lower()
path_definition[method_lower] = {
sw.operation_id: d.endpoint or get_swagger_title(d.func),
sw.responses: responses_definition
}
if d.func.__doc__:
path_definition[method_lower][sw.description] = d.func.__doc__
if parameters_definition:
path_definition[method_lower][sw.parameters] = parameters_definition
if d.authenticator is None:
path_definition[method_lower][sw.security] = []
elif d.authenticator is not USE_DEFAULT:
security = self._get_security(d.authenticator)
path_definition[method_lower][sw.security] = security
return path_definitions
def _get_paths(self, paths, default_headers_schema, default_security=None):
path_definitions = {}
for path, methods in paths.items():
swagger_path, path_args = format_path_for_swagger(path)
# Different Flask paths might correspond to the same Swagger path
# because of Flask URL path converters. In this case, let's just
# work off the same path definitions.
if swagger_path in path_definitions:
path_definition = path_definitions[swagger_path]
else:
path_definitions[swagger_path] = path_definition = {}
if path_args:
path_params = [{
sw.name: path_arg.name,
sw.required: True,
sw.in_: sw.path,
sw.style: sw.simple,
sw.schema: {
sw.type_:
self.flask_converters_to_swagger_types[path_arg.type]
},
} for path_arg in path_args]
# We have to check for an ugly case here. If different Flask
# paths that map to the same Swagger path use different URL
# converters for the same parameter, we have a problem. Let's
# just throw an error in this case.
if sw.parameters in path_definition:
verify_parameters_are_the_same(
path_definition[sw.parameters], path_params)
path_definition[sw.parameters] = path_params
for method, d in methods.items():
responses_definition = {
sw.default:
self._get_response_definition(self.default_response_schema)
}
if d.response_body_schema:
for status_code, schema in d.response_body_schema.items():
if schema is not None:
response_definition = self._get_response_definition(
schema)
else:
response_definition = {
sw.description: "No response body."
}
responses_definition[str(
status_code)] = response_definition
parameters_definition = []
if d.query_string_schema:
parameters_definition.extend(
self._convert_schema_to_list_of_parameters(
schema=d.query_string_schema,
converter=self._query_string_converter,
in_=sw.query,
))
if d.headers_schema is USE_DEFAULT:
headers_schema = default_headers_schema
else:
headers_schema = d.headers_schema
if headers_schema:
parameters_definition.extend(
self._convert_schema_to_list_of_parameters(
schema=headers_schema,
converter=self._headers_converter,
in_=sw.header,
))
request_body = None
if d.request_body_schema:
schema = d.request_body_schema
request_body = {
sw.required: True,
sw.content: {
"application/json": {
sw.schema:
get_ref_schema(self._ref_base, schema)
}
},
}
method_lower = method.lower()
path_definition[method_lower] = {
sw.operation_id: d.endpoint or get_swagger_title(d.func),
sw.responses: responses_definition,
}
if d.func.__doc__:
path_definition[method_lower][
sw.description] = d.func.__doc__
if parameters_definition:
path_definition[method_lower][
sw.parameters] = parameters_definition
if request_body:
path_definition[method_lower][
sw.request_body] = request_body
if not d.authenticators:
path_definition[method_lower][sw.security] = []
else:
non_default = False
security = []
for authenticator in d.authenticators:
if authenticator is not USE_DEFAULT:
security.extend(
self.authenticator_converter.
get_security_requirements(authenticator))
non_default = True
elif default_security is not None:
security.extend(default_security)
if non_default:
path_definition[method_lower][sw.security] = security
if d.tags:
path_definition[method_lower][sw.tags] = d.tags
return path_definitions
def _get_schema(self, schema):
ref = {sw.ref: _get_ref(get_swagger_title(schema))}
return ref if not schema.many else {sw.type_: sw.array, sw.items: ref}
