def test_4605_regression(self):
generator = SchemaGenerator()
prefix = generator.determine_path_prefix([
'/api/v1/items/',
'/auth/convert-token/'
])
assert prefix == '/'
def test_4605_regression(self):
generator = SchemaGenerator()
prefix = generator.determine_path_prefix([
'/api/v1/items/',
'/auth/convert-token/'
])
assert prefix == '/'
class OpenAPISchemaGenerator(object):
"""
This class iterates over all registered API endpoints and returns an appropriate OpenAPI 2.0 compliant schema.
Method implementations shamelessly stolen and adapted from rest-framework ``SchemaGenerator``.
"""
endpoint_enumerator_class = EndpointEnumerator
reference_resolver_class = ReferenceResolver
def __init__(self,
info,
version='',
url=None,
patterns=None,
urlconf=None,
swagger_settings=_swagger_settings):
"""
:param openapi.Info info: information about the API
:param str version: API version string; if omitted, `info.default_version` will be used
:param str url: API scheme, host and port; if ``None`` is passed and ``DEFAULT_API_URL`` is not set, the url
will be inferred from the request made against the schema view, so you should generally not need to set
this parameter explicitly; if the empty string is passed, no host and scheme will be emitted
If `url` is not ``None`` or the empty string, it must be a scheme-absolute uri (i.e. starting with http://
or https://), and any path component is ignored;
See also: :ref:`documentation on base URL construction <custom-spec-base-url>`
:param patterns: if given, only these patterns will be enumerated for inclusion in the API spec
:param urlconf: if patterns is not given, use this urlconf to enumerate patterns;
if not given, the default urlconf is used
:param swagger_settings: if given global swagger_settings are overridden with local settings
"""
self._gen = SchemaGenerator(info.title, url,
info.get('description',
''), patterns, urlconf)
self.info = info
self.swagger_settings = swagger_settings
self.version = version
self.consumes = []
self.produces = []
if url is None and swagger_settings.DEFAULT_API_URL is not None:
url = swagger_settings.DEFAULT_API_URL
if url:
parsed_url = urlparse.urlparse(url)
if parsed_url.scheme not in ('http',
'https') or not parsed_url.netloc:
raise SwaggerGenerationError(
"`url` must be an absolute HTTP(S) url")
if parsed_url.path:
logger.warning(
"path component of api base URL %s is ignored; use FORCE_SCRIPT_NAME instead"
% url)
@property
def url(self):
return self._gen.url
def get_security_definitions(self):
"""Get the security schemes for this API. This determines what is usable in security requirements,
and helps clients configure their authorization credentials.
:return: the security schemes usable with this API
:rtype: dict[str,dict] or None
"""
security_definitions = self.swagger_settings.SECURITY_DEFINITIONS
if security_definitions is not None:
security_definitions = SwaggerDict._as_odict(
security_definitions, {})
return security_definitions
def get_security_requirements(self, security_definitions):
"""Get the base (global) security requirements of the API. This is never called if
:meth:`.get_security_definitions` returns `None`.
:param security_definitions: security definitions as returned by :meth:`.get_security_definitions`
:return: the security schemes accepted by default
:rtype: list[dict[str,list[str]]] or None
"""
security_requirements = self.swagger_settings.SECURITY_REQUIREMENTS
if security_requirements is None:
security_requirements = [{
security_scheme: []
} for security_scheme in security_definitions]
security_requirements = [
SwaggerDict._as_odict(sr, {}) for sr in security_requirements
]
security_requirements = sorted(security_requirements, key=list)
return security_requirements
def get_schema(self, request=None, public=False):
"""Generate a :class:`.Swagger` object representing the API schema.
:param request: the request used for filtering accessible endpoints and finding the spec URI
:type request: rest_framework.request.Request or None
:param bool public: if True, all endpoints are included regardless of access through `request`
:return: the generated Swagger specification
:rtype: openapi.Swagger
"""
endpoints = self.get_endpoints(request)
components = self.reference_resolver_class(openapi.SCHEMA_DEFINITIONS,
force_init=True)
self.consumes = get_consumes(api_settings.DEFAULT_PARSER_CLASSES)
self.produces = get_produces(api_settings.DEFAULT_RENDERER_CLASSES,
self.swagger_settings)
paths, prefix = self.get_paths(endpoints, components, request, public)
security_definitions = self.get_security_definitions()
if security_definitions:
security_requirements = self.get_security_requirements(
security_definitions)
else:
security_requirements = None
url = self.url
if url is None and request is not None:
url = request.build_absolute_uri()
return openapi.Swagger(info=self.info,
paths=paths,
consumes=self.consumes or None,
produces=self.produces or None,
security_definitions=security_definitions,
security=security_requirements,
_url=url,
_prefix=prefix,
_version=self.version,
**dict(components))
def create_view(self, callback, method, request=None):
"""Create a view instance from a view callback as registered in urlpatterns.
:param callback: view callback registered in urlpatterns
:param str method: HTTP method
:param request: request to bind to the view
:type request: rest_framework.request.Request or None
:return: the view instance
"""
view = self._gen.create_view(callback, method, request)
overrides = getattr(callback, '_swagger_auto_schema', None)
if overrides is not None:
# decorated function based view must have its decorator information passed on to the re-instantiated view
for method, _ in overrides.items():
view_method = getattr(view, method, None)
if view_method is not None: # pragma: no cover
setattr(view_method.__func__, '_swagger_auto_schema',
overrides)
setattr(view, 'swagger_fake_view', True)
return view
def coerce_path(self, path, view):
"""Coerce {pk} path arguments into the name of the model field, where possible. This is cleaner for an
external representation (i.e. "this is an identifier", not "this is a database primary key").
:param str path: the path
:param rest_framework.views.APIView view: associated view
:rtype: str
"""
if '{pk}' not in path:
return path
model = getattr(get_queryset_from_view(view), 'model', None)
if model:
field_name = get_pk_name(model)
else:
field_name = 'id'
return path.replace('{pk}', '{%s}' % field_name)
def get_endpoints(self, request):
"""Iterate over all the registered endpoints in the API and return a fake view with the right parameters.
:param request: request to bind to the endpoint views
:type request: rest_framework.request.Request or None
:return: {path: (view_class, list[(http_method, view_instance)])
:rtype: dict[str,(type,list[(str,rest_framework.views.APIView)])]
"""
enumerator = self.endpoint_enumerator_class(self._gen.patterns,
self._gen.urlconf,
request=request)
endpoints = enumerator.get_api_endpoints()
view_paths = defaultdict(list)
view_cls = {}
for path, method, callback in endpoints:
view = self.create_view(callback, method, request)
path = self.coerce_path(path, view)
view_paths[path].append((method, view))
view_cls[path] = callback.cls
return {
path: (view_cls[path], methods)
for path, methods in view_paths.items()
}
def get_operation_keys(self, subpath, method, view):
"""Return a list of keys that should be used to group an operation within the specification. ::
/users/ ("users", "list"), ("users", "create")
/users/{pk}/ ("users", "read"), ("users", "update"), ("users", "delete")
/users/enabled/ ("users", "enabled") # custom viewset list action
/users/{pk}/star/ ("users", "star") # custom viewset detail action
/users/{pk}/groups/ ("users", "groups", "list"), ("users", "groups", "create")
/users/{pk}/groups/{pk}/ ("users", "groups", "read"), ("users", "groups", "update")
:param str subpath: path to the operation with any common prefix/base path removed
:param str method: HTTP method
:param view: the view associated with the operation
:rtype: list[str]
"""
return self._gen.get_keys(subpath, method, view)
def determine_path_prefix(self, paths):
"""
Given a list of all paths, return the common prefix which should be
discounted when generating a schema structure.
This will be the longest common string that does not include that last
component of the URL, or the last component before a path parameter.
For example: ::
/api/v1/users/
/api/v1/users/{pk}/
The path prefix is ``/api/v1/``.
:param list[str] paths: list of paths
:rtype: str
"""
return self._gen.determine_path_prefix(paths)
def should_include_endpoint(self, path, method, view, public):
"""Check if a given endpoint should be included in the resulting schema.
:param str path: request path
:param str method: http request method
:param view: instantiated view callback
:param bool public: if True, all endpoints are included regardless of access through `request`
:returns: true if the view should be excluded
:rtype: bool
"""
return public or self._gen.has_view_permissions(path, method, view)
def get_paths_object(self, paths):
"""Construct the Swagger Paths object.
:param OrderedDict[str,openapi.PathItem] paths: mapping of paths to :class:`.PathItem` objects
:returns: the :class:`.Paths` object
:rtype: openapi.Paths
"""
return openapi.Paths(paths=paths)
def get_paths(self, endpoints, components, request, public):
"""Generate the Swagger Paths for the API from the given endpoints.
:param dict endpoints: endpoints as returned by get_endpoints
:param ReferenceResolver components: resolver/container for Swagger References
:param Request request: the request made against the schema view; can be None
:param bool public: if True, all endpoints are included regardless of access through `request`
:returns: the :class:`.Paths` object and the longest common path prefix, as a 2-tuple
:rtype: tuple[openapi.Paths,str]
"""
if not endpoints:
return openapi.Paths(paths={}), ''
prefix = self.determine_path_prefix(list(endpoints.keys())) or ''
assert '{' not in prefix, "base path cannot be templated in swagger 2.0"
paths = OrderedDict()
for path, (view_cls, methods) in sorted(endpoints.items()):
operations = {}
for method, view in methods:
if not self.should_include_endpoint(path, method, view,
public):
continue
operation = self.get_operation(view, path, prefix, method,
components, request)
if operation is not None:
operations[method.lower()] = operation
if operations:
# since the common prefix is used as the API basePath, it must be stripped
# from individual paths when writing them into the swagger document
path_suffix = path[len(prefix):]
if not path_suffix.startswith('/'):
path_suffix = '/' + path_suffix
paths[path_suffix] = self.get_path_item(
path, view_cls, operations)
return self.get_paths_object(paths), prefix
def get_operation(self, view, path, prefix, method, components, request):
"""Get an :class:`.Operation` for the given API endpoint (path, method). This method delegates to
:meth:`~.inspectors.ViewInspector.get_operation` of a :class:`~.inspectors.ViewInspector` determined
according to settings and :func:`@swagger_auto_schema <.swagger_auto_schema>` overrides.
:param view: the view associated with this endpoint
:param str path: the path component of the operation URL
:param str prefix: common path prefix among all endpoints
:param str method: the http method of the operation
:param openapi.ReferenceResolver components: referenceable components
:param Request request: the request made against the schema view; can be None
:rtype: openapi.Operation
"""
operation_keys = self.get_operation_keys(path[len(prefix):], method,
view)
overrides = self.get_overrides(view, method)
# the inspector class can be specified, in decreasing order of priorty,
# 1. globaly via DEFAULT_AUTO_SCHEMA_CLASS
view_inspector_cls = self.swagger_settings.DEFAULT_AUTO_SCHEMA_CLASS
# 2. on the view/viewset class
view_inspector_cls = getattr(view, 'swagger_schema',
view_inspector_cls)
# 3. on the swagger_auto_schema decorator
view_inspector_cls = overrides.get('auto_schema', view_inspector_cls)
if view_inspector_cls is None:
return None
view_inspector = view_inspector_cls(view, path, method, components,
request, overrides, operation_keys,
self.swagger_settings)
operation = view_inspector.get_operation(operation_keys)
if operation is None:
return None
if 'consumes' in operation and set(operation.consumes) == set(
self.consumes):
del operation.consumes
if 'produces' in operation and set(operation.produces) == set(
self.produces):
del operation.produces
return operation
def get_path_item(self, path, view_cls, operations):
"""Get a :class:`.PathItem` object that describes the parameters and operations related to a single path in the
API.
:param str path: the path
:param type view_cls: the view that was bound to this path in urlpatterns
:param dict[str,openapi.Operation] operations: operations defined on this path, keyed by lowercase HTTP method
:rtype: openapi.PathItem
"""
path_parameters = self.get_path_parameters(path, view_cls)
return openapi.PathItem(parameters=path_parameters, **operations)
def get_overrides(self, view, method):
"""Get overrides specified for a given operation.
:param view: the view associated with the operation
:param str method: HTTP method
:return: a dictionary containing any overrides set by :func:`@swagger_auto_schema <.swagger_auto_schema>`
:rtype: dict
"""
method = method.lower()
action = getattr(view, 'action', method)
action_method = getattr(view, action, None)
overrides = getattr(action_method, '_swagger_auto_schema', {})
if method in overrides:
overrides = overrides[method]
return copy.deepcopy(overrides)
def get_path_parameters(self, path, view_cls):
"""Return a list of Parameter instances corresponding to any templated path variables.
:param str path: templated request path
:param type view_cls: the view class associated with the path
:return: path parameters
:rtype: list[openapi.Parameter]
"""
parameters = []
queryset = get_queryset_from_view(view_cls)
for variable in sorted(uritemplate.variables(path)):
model, model_field = get_queryset_field(queryset, variable)
attrs = get_basic_type_info(model_field) or {
'type': openapi.TYPE_STRING
}
if getattr(
view_cls, 'lookup_field',
None) == variable and attrs['type'] == openapi.TYPE_STRING:
attrs['pattern'] = getattr(view_cls, 'lookup_value_regex',
attrs.get('pattern', None))
if model_field and getattr(model_field, 'help_text', False):
description = model_field.help_text
elif model_field and getattr(model_field, 'primary_key', False):
description = get_pk_description(model, model_field)
else:
description = None
field = openapi.Parameter(name=variable,
description=force_real_str(description),
required=True,
in_=openapi.IN_PATH,
**attrs)
parameters.append(field)
return parameters
class OpenAPISchemaGenerator(object):
endpoint_enumerator_class = EndpointEnumerator
def __init__(self, name='API', version=''):
self._gen = SchemaGenerator(name, None, '', None, None)
self.version = version
self.consumes = []
self.produces = []
@property
def url(self):
return self._gen.url
def create_view(self, callback, method, request=None):
"""Create a view instance from a view callback as registered in urlpatterns.
:param callback: view callback registered in urlpatterns
:param str method: HTTP method
:param request: request to bind to the view
:type request: rest_framework.request.Request or None
:return: the view instance
"""
view = self._gen.create_view(callback, method, request)
overrides = getattr(callback, '_swagger_auto_schema', None)
if overrides is not None:
# decorated function based view must have its decorator information passed on to the re-instantiated view
for method, _ in overrides.items():
view_method = getattr(view, method, None)
if view_method is not None: # pragma: no cover
setattr(view_method.__func__, '_swagger_auto_schema', overrides)
setattr(view, 'swagger_fake_view', True)
return view
def get_schema(self, request=None, public=False):
endpoints = self.get_endpoints(request)
# return self.get_paths(endpoints, None, request, public=False)
# import pdb; pdb.set_trace()
register_api = self.get_register_api(endpoints, None, request, public=False)
return self.handle_api_path(register_api)
def get_endpoints(self, request):
enumerator = self.endpoint_enumerator_class(self._gen.patterns, self._gen.urlconf, request=request)
endpoints = []
# import pdb; pdb.set_trace()
enumerator.get_api_endpoints(final_arrays=endpoints)
ret=[]
for group in endpoints:
#print(group)
group_points=group['points']
view_paths = defaultdict(list)
view_cls = {}
for path, method, callback in group_points:
view = self.create_view(callback, method, request)
# path = self.coerce_path(path, view)
view_paths[path].append((method, view))
view_cls[path] = callback.cls
#返回的是一个json-dict
ret.append({"prefix":group['prefix'],"points":{path: (view_cls[path], methods) for path, methods in view_paths.items()}})
return ret
def determine_path_prefix(self, paths):
"""
Given a list of all paths, return the common prefix which should be
discounted when generating a schema structure.
This will be the longest common string that does not include that last
component of the URL, or the last component before a path parameter.
For example: ::
/api/v1/users/
/api/v1/users/{pk}/
The path prefix is ``/api/v1/``.
:param list[str] paths: list of paths
:rtype: str
"""
return self._gen.determine_path_prefix(paths)
def _get_description_section(self, view, header, description):
lines = [line for line in description.splitlines()]
current_section = ''
sections = {'': ''}
for line in lines:
if header_regex.match(line):
current_section, seperator, lead = line.partition(':')
sections[current_section] = lead.strip()
else:
sections[current_section] += '\n' + line
# TODO: SCHEMA_COERCE_METHOD_NAMES appears here and in `SchemaGenerator.get_keys`
coerce_method_names = api_settings.SCHEMA_COERCE_METHOD_NAMES
if header in sections:
return sections[header].strip()
if header in coerce_method_names:
if coerce_method_names[header] in sections:
return sections[coerce_method_names[header]].strip()
return sections[''].strip()
def split_summary_from_description(self, description):
"""Decide if and how to split a summary out of the given description. The default implementation
uses the first paragraph of the description as a summary if it is less than 120 characters long.
:param description: the full description to be analyzed
:return: summary and description
:rtype: (str,str)
"""
# https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings
summary = None
summary_max_len = 120 # OpenAPI 2.0 spec says summary should be under 120 characters
sections = description.split('\n', 1)
if len(sections) == 2:
sections[0] = sections[0].strip()
if len(sections[0]) < summary_max_len:
summary, description = sections
description = description.strip()
return summary, description
def handle_api_path(self, api_list):
'''
处理正则数据
'''
# path_pamas_pattern
result = []
pattern_param = re.compile('\{((?!\/).)*\}')
pattern_str = '[^/]*'
g = lambda pathregx: True if pattern_str in pathregx else False
for api in api_list:
origin_path = api['origin_path']
regex_path = pattern_param.sub(pattern_str, origin_path)
is_regex = g(regex_path)
if is_regex:
regex_path = "^" + regex_path + "$"
method = api['method']
desc = api["desc"]
name = api["name"]
regex_api = {
"path": regex_path,
"origin_path": origin_path,
"method": method,
"desc": desc[:500],
"api_name": name[:30],
"is_regex": is_regex,
}
result.append(regex_api)
logger.info("path=%s, method=%s, regx=%s" % (origin_path, method, regex_path))
return result
def get_register_api(self, top, components, request, public):
'''
按照注册中心的数据格式, 重新构建数据结构
'''
if not top:
return None
result = []
for category in top:
# import pdb; pdb.set_trace()
endpoints=category['points']
if endpoints is None or len(endpoints)==0:
continue
for path, (view_cls, methods) in sorted(endpoints.items()):
for method, view in methods:
method_lower=method.lower()
method_name = getattr(view, 'action', method_lower)
method_docstring = getattr(view, method_name, None).__doc__
if method_docstring:
method_docstring = self._get_description_section(view, method.lower(),
formatting.dedent(smart_text(method_docstring)))
else:
method_docstring = self._get_description_section(view, getattr(view, 'action', method.lower()),
view.get_view_description())
if not method_docstring:
method_docstring = "_"
(name, desc) = self.split_summary_from_description(method_docstring)
if name is None:
name = desc
_path = {
"name": name,
# "path": path,
"method": method_lower,
"origin_path": path,
# "is_regex": False,
"desc": desc,
# "version": ""
}
result.append(_path)
return result
def get_paths(self, top, components, request, public):
"""
Generate the Swagger Paths for the API from the given endpoints.
"""
if not top:
return None
ret=[]
# import pdb; pdb.set_trace()
for category in top:
# print('~~~~~~~~~')
endpoints=category['points']
if endpoints is None or len(endpoints)==0:
continue
prefix = self.determine_path_prefix(list(endpoints.keys())) or ''
assert '{' not in prefix, "base path cannot be templated in swagger 2.0"
paths = {}
for path, (view_cls, methods) in sorted(endpoints.items()):
_path={}
for method, view in methods:
# print(method)
# if not self.should_include_endpoint(path, method, view, public):
# continue
method_lower=method.lower()
method_name = getattr(view, 'action', method_lower)
method_docstring = getattr(view, method_name, None).__doc__
if method_docstring:
method_docstring = self._get_description_section(view, method.lower(),
formatting.dedent(smart_text(method_docstring)))
else:
method_docstring = self._get_description_section(view, getattr(view, 'action', method.lower()),
view.get_view_description())
if not method_docstring:
method_docstring = "_"
(_name, _desc) = self.split_summary_from_description(method_docstring)
if _name is None:
_name = _desc
_path[method_lower]={"name": _name, "description": _desc}
path_suffix = path[len(prefix):]
if not path_suffix.startswith('/'):
path_suffix = '/' + path_suffix
paths[path_suffix]=_path
# #检查是否有basePath可以融合在一起
# _current_len=len(ret)
# for i in range(_current_len):
# _current_prefix=ret[i]['basePath']
# if prefix.find(_current_prefix)>=0:
# ret[i]['paths'].update(paths)
#
# paths=None
# break
# elif _current_prefix.find(prefix)>=0:
# ret[i]['basePath']=prefix
# ret[i]['paths'].update(paths)
# paths=None
# break
if not paths is None:
ret.append({"basePath":prefix,"basePathArray":prefix.strip("/").split("/"),"paths":paths})
return ret