Django REST框架的Swagger 2.0

Question

Django REST框架的Swagger 2.0

djangodjango-rest-frameworkswagger-uiswagger-2.0openapi

19

我很难配置Swagger UI，这里有非常详细的文档：https://django-rest-swagger.readthedocs.io/en/latest/

YAML docstrings已经被弃用。有人知道如何从Python代码中配置Swagger UI吗？或者应该更改哪个文件以将API端点分组，向每个端点添加注释，在Swagger UI中添加查询参数字段？

- Teodor Scorpan

你有类似于另一个基于Swagger的API上想要进行分组的示例吗？在分组方面，Swagger可能会非常限制 - 我编写了定制模板来完成此操作。我想评论是从端点方法的docstrings中添加的。如果查询参数被正确定义，它们应该出现...尽管我依稀记得有一些情况它们不会出现。 - Steve

4个回答

7

所以，看起来发生的事情是django-rest-framework 添加了新的SchemeGenerator，但它只完成了一半，并且缺少从代码文档中生成操作描述的能力，并且有一个关于此问题的开放问题，预计在3.5.0版本中解决。

同时，django-rest-swagger已经更新了他们的代码以适应新的SchemaGenerator，这暂时是一个破坏性变更。

非常奇怪的一系列事件导致了这个问题 ): 希望很快会解决。目前，建议的答案是唯一的选择。

- Daniel Dror

7

编辑 - 自从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',
}

！以下方法已过时。

由于我在这里找不到任何可行的选项（链接），因此我简单地创建了自己的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', ())

创建了Swagger视图：

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')

- Lucianovici

0

使用所提出的解决方案有点钻空子，但效果很好。在实施所提出的解决方案时可能会遇到一些问题，但此文档逐步说明了Django Rest Swagger 2集成以及所遇到的问题： Django Rest Swagger 2完整文档

虽然来得有些晚，但它可能对现在寻求帮助的某个人有所帮助。

- Haziq

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- bitnik · Accepted Answer

这是我成功完成它的方法：

基本 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规范来创建自定义数据。