很难配置 Swagger UI 以下是非常解释性的文档：https://django-rest-swagger.readthedocs.io/en/latest/
不推荐使用 YAML 文档字符串。有人知道如何从 python 代码中配置 Swagger UI 吗？或者我应该更改什么文件来分组 api 端点、将 cmets 添加到每个端点、在 Swagger UI 中添加查询参数字段？
【问题讨论】：
标签： django django-rest-framework swagger-ui swagger-2.0 openapi
这就是我设法做到的：
基础 urls.py
urlpatterns = [
...
url(r'^api/', include('api.urls', namespace='api')),
url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')),
...
]
api.urls.py
urlpatterns = [
url(r'^$', schema_view, name='swagger'),
url(r'^article/(?P<pk>[0-9]+)/$',
ArticleDetailApiView.as_view(actions={'get': 'get_article_by_id'}),
name='article_detail_id'),
url(r'^article/(?P<name>.+)/(?P<pk>[0-9]+)/$',
ArticleDetailApiView.as_view(actions={'get': 'get_article'}),
name='article_detail'),
]
api.views.py。在 MyOpenAPIRenderer 中，我更新数据字典以添加描述、查询字段并更新类型或所需功能。
class MyOpenAPIRenderer(OpenAPIRenderer):
def add_customizations(self, data):
super(MyOpenAPIRenderer, self).add_customizations(data)
data['paths']['/article/{name}/{pk}/']['get'].update(
{'description': 'Some **description**',
'parameters': [{'description': 'Add some description',
'in': 'path',
'name': 'pk',
'required': True,
'type': 'integer'},
{'description': 'Add some description',
'in': 'path',
'name': 'name',
'required': True,
'type': 'string'},
{'description': 'Add some description',
'in': 'query',
'name': 'a_query_param',
'required': True,
'type': 'boolean'},
]
})
# data['paths']['/article/{pk}/']['get'].update({...})
data['basePath'] = '/api'
@api_view()
@renderer_classes([MyOpenAPIRenderer, SwaggerUIRenderer])
def schema_view(request):
generator = SchemaGenerator(title='A title', urlconf='api.urls')
schema = generator.get_schema(request=request)
return Response(schema)
class ArticleDetailApiView(ViewSet):
@detail_route(renderer_classes=(StaticHTMLRenderer,))
def get_article_by_id(self, request, pk):
pass
@detail_route(renderer_classes=(StaticHTMLRenderer,))
def get_article(self, request, name, pk):
pass
django-rest-swagger (2.0.7) 更新：仅将 add_customizations 替换为 get_customizations。
views.py
class MyOpenAPIRenderer(OpenAPIRenderer):
def get_customizations(self):
data = super(MyOpenAPIRenderer, self).get_customizations()
data['paths'] = custom_data['paths']
data['info'] = custom_data['info']
data['basePath'] = custom_data['basePath']
return data
您可以阅读swagger specification 来创建自定义数据。
【讨论】：
add_customizations？我根本无法在源代码中找到它。因此，这个解决方案对我不起作用。
add_customizations 或任何包含上述“数据”变量的类似命名函数
custom_data是用户定义的吗？
所以，似乎发生的事情是 django-rest-frameowrk added the new SchemeGenerator，但它是半生不熟的，并且缺少从代码文档生成操作描述的能力，并且有一个 open issue about it，由于 3.5.0 .
与此同时，django-rest-swagger 继续更新了他们的代码以使用新的 SchemaGenerator，这使其现在成为 breaking change。
一系列非常奇怪的事件导致了这种情况）：希望这将很快得到解决。目前，建议的答案是唯一的选择。
【讨论】：
编辑 - 因为 swagger 版本 2.2.0 和 rest framework 3.9.2 创建了一个这样的自定义架构：
from rest_framework.schemas import AutoSchema
class CustomSchema(AutoSchema):
def get_link(self, path, method, base_url):
link = super().get_link(path, method, base_url)
link._fields += self.get_core_fields()
return link
def get_core_fields(self):
return getattr(self.view, 'coreapi_fields', ())
然后，只需使用DEFAULT_SCHEMA_CLASS 设置。
REST_FRAMEWORK = {
'DEFAULT_SCHEMA_CLASS': 'common.schema.CustomSchema',
}
！以下方法已过时。
由于我找不到任何可行的选项 here 我只是创建了自己的 SchemaGenerator，如下所示：
from rest_framework.schemas import SchemaGenerator
class MySchemaGenerator(SchemaGenerator):
title = 'REST API Index'
def get_link(self, path, method, view):
link = super(MySchemaGenerator, self).get_link(path, method, view)
link._fields += self.get_core_fields(view)
return link
def get_core_fields(self, view):
return getattr(view, 'coreapi_fields', ())
创建了招摇视图：
from rest_framework.permissions import AllowAny
from rest_framework.renderers import CoreJSONRenderer
from rest_framework.response import Response
from rest_framework.views import APIView
from rest_framework_swagger import renderers
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 = MySchemaGenerator()
schema = generator.get_schema(request=request)
return Response(schema)
在 urls.py 中使用这个视图：
url(r'^docs/$', SwaggerSchemaView.as_view()),
在 APIView 中添加自定义字段：
class EmailValidator(APIView):
coreapi_fields = (
coreapi.Field(
name='email',
location='query',
required=True,
description='Email Address to be validated',
type='string'
),
)
def get(self, request):
return Response('something')
【讨论】：
使用建议的解决方案有点麻烦，但效果很好，实施建议的解决方案可能会遇到一些问题，但此文档解释了 django rest swagger 2 集成以及逐步面临的问题： Django Rest Swagger 2 comprehensive documentation
晚了很多，但它可能对现在寻求帮助的人有所帮助。
【讨论】：