0x01
最近在项目中要对api进行大规模重构，并且工具源码注释生成文档，比较swagger和spihx之后，觉得swagger更适合做api文档，可以在web页面中直接请求对应的api，很是方便。使用最新版的django-rest-swagger(drs)生成djangorestframework(drf)生成文档的时候，drs只会根据视图中的docstring来生成Link(swagger的单条文档记录)的描述，根据ViewSet中的serializer中定义的fields以及pagination_class定义的分页类来生成parameters，如果想要根据文档来插入一些parameters时，可以发现drs的可定制化程度很低，于是我决定做一些定制化。
0x02 代码
在制定花的过程中我主要重写了drf中的SchemaGenerator的get_description，把视图中的docstring按照yaml格式解析出来，并且返回docstring中的第一行作为description，如果视图没有docstring的话，_SchemaGenerator会按照视图名称自动生成相应的description。接下来是重写get_link方法，前面说过，一条Link是swagger页面中的一条文档记录，如果有yamlobj的话，则根据固定的格式解析yamlobj，然后解析出来的属性加到Link当中去。最后重写get_swagger_view 方法，使用新写的SchemaGenerator。
from rest_framework.schemas import SchemaGenerator as _SchemaGenerator
from rest_framework_swagger import renderers
from rest_framework.compat import coreapi, urlparse
from django.utils.encoding import smart_text
from rest_framework.utils import formatting
class SchemaGenerator(_SchemaGenerator):
def get_description(self, path, method, view):
method_name = getattr(view, 'action', method.lower())
method_docstring = getattr(view, method_name, None).__doc__
self.yamlobj = None
if method_docstring:
method_docstring = formatting.dedent(smart_text(method_docstring))
self.yamlobj = yaml.load(method_docstring)
return method_docstring.splitlines()[0]
return super(SchemaGenerator, self).get_description(path, method, view)
def get_link(self, path, method, view):
"""
Return a `coreapi.Link` instance for the given endpoint.
"""
fields = self.get_path_fields(path, method, view)
fields += self.get_serializer_fields(path, method, view)
fields += self.get_pagination_fields(path, method, view)
fields += self.get_filter_fields(path, method, view)
if fields and any([field.location in ('form', 'body') for field in fields]):
encoding = self.get_encoding(path, method, view)
else:
encoding = None
description = self.get_description(path, method, view)
if isinstance(self.yamlobj, dict):
def get_localtion(parameter):
if method == 'GET':
return 'query'
return parameter.get('paramType', 'formData')
parameters = self.yamlobj.get('parameters', [])
fields += [coreapi.Field(name=x['name'], location=get_localtion(x), required=x.get('required', True, ), description=x.get('description', ''), type=x.get('type', 'string')) for x in parameters]
if self.url and path.startswith('/'):
path = path[1:]
return coreapi.Link(
url=urlparse.urljoin(self.url, path),
action=method.lower(),
encoding=encoding,
fields=fields,
description=description
)
def get_swagger_view(title=None, url=None, patterns=None, urlconf=None):
"""
Returns schema view which renders Swagger/OpenAPI.
"""
class SwaggerSchemaView(APIView):
_ignore_model_permissions = True
exclude_from_schema = True
permission_classes = [AllowAny]
renderer_classes = [
CoreJSONRenderer,
renderers.OpenAPIRenderer,
renderers.SwaggerUIRenderer
]
def get(self, request):
generator = SchemaGenerator(
title=title,
url=url,
patterns=patterns,
urlconf=urlconf
)
schema = generator.get_schema(request=request)
if not schema:
raise exceptions.ValidationError(
'The schema generator did not return a schema Document'
)
return Response(schema)
return SwaggerSchemaView.as_view()