django框架集成swagger以及自定义参数问题

django集成swagger以及自定义参数问题

• 介绍
• • 开发版本
  • 修改settings.py
  • 在app下面创建schema_view.py
  • 实际应用
  • 修改url.py
  • 效果展示
  • 总结

介绍

我们在实际的开发工作中需要将django框架与swagger进行集成，用于生成API文档。网上也有一些关于django集成swagger的例子，但由于每个项目使用的依赖版本不一样，因此可能有些例子并不适合我们。我也是在实际集成过程中遇到了一些问题，例如如何自定义参数等问题，最终成功集成，并将结果分享给大家。

开发版本

我开发使用的依赖版本，我所使用的都是截止发稿日期为止最新的版本：

Django 2.2.7

django-rest-swagger 2.2.0

djangorestframework 3.10.3

修改settings.py

1、项目引入rest_framework_swagger依赖

INSTALLED_APPS = [
    ......
    'rest_framework_swagger',
	......
]
           

2、设置DEFAULT_SCHEMA_CLASS，此处不设置后续会报错。

REST_FRAMEWORK = {
    ......
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema',
	......
}
           

在app下面创建schema_view.py

在此文件中，我们要继承coreapi中的SchemaGenerator类，并重写get_links方法，重写的目的就是实现我们自定义参数，并且能在页面上展示。此处直接复制过去使用即可。

from rest_framework.schemas import SchemaGenerator
from rest_framework.schemas.coreapi import LinkNode, insert_into
from rest_framework.renderers import *
from rest_framework_swagger import renderers
from rest_framework.response import Response
from rest_framework.decorators import APIView
from rest_framework.permissions import AllowAny,IsAuthenticated,IsAuthenticatedOrReadOnly
from django.http import JsonResponse


class MySchemaGenerator(SchemaGenerator):

    def get_links(self, request=None):
        links = LinkNode()

        paths = []
        view_endpoints = []
        for path, method, callback in self.endpoints:
            view = self.create_view(callback, method, request)
            path = self.coerce_path(path, method, view)
            paths.append(path)
            view_endpoints.append((path, method, view))

        # Only generate the path prefix for paths that will be included
        if not paths:
            return None
        prefix = self.determine_path_prefix(paths)

        for path, method, view in view_endpoints:
            if not self.has_view_permissions(path, method, view):
                continue
            link = view.schema.get_link(path, method, base_url=self.url)
            # 添加下面这一行方便在views编写过程中自定义参数.
            link._fields += self.get_core_fields(view)

            subpath = path[len(prefix):]
            keys = self.get_keys(subpath, method, view)

            # from rest_framework.schemas.generators import LinkNode, insert_into
            insert_into(links, keys, link)

        return links

    # 从类中取出我们自定义的参数, 交给swagger 以生成接口文档.
    def get_core_fields(self, view):
        return getattr(view, 'coreapi_fields', ())


class SwaggerSchemaView(APIView):
    _ignore_model_permissions = True
    exclude_from_schema = True

    #permission_classes = [AllowAny]
    # 此处涉及最终展示页面权限问题，如果不需要认证，则使用AllowAny，这里需要权限认证，因此使用IsAuthenticated
    permission_classes = [IsAuthenticated]
    # from rest_framework.renderers import *
    renderer_classes = [
        CoreJSONRenderer,
        renderers.OpenAPIRenderer,
        renderers.SwaggerUIRenderer
    ]

    def get(self, request):
        # 此处的titile和description属性是最终页面最上端展示的标题和描述
        generator = MySchemaGenerator(title='API说明文档',description='''接口测试、说明文档''')

        schema = generator.get_schema(request=request)

        # from rest_framework.response import Response
        return Response(schema)


def DocParam(name="default", location="query",required=True, description=None, type="string",
             *args, **kwargs):
    return coreapi.Field(name=name, location=location,
                         required=required, description=description,
                         type=type)


           

实际应用

在你的应用中定义一个接口，并发布。我这里使用一个测试接口进行验证。

注意

1、所有的接口必须采用calss的方式定义，因为要继承APIView。

2、class下方的注释post，是用来描述post方法的作用，会在页面上进行展示。

3、coreapi_fields 中定义的属性name是参数名称，location是传值方式，我这里一个采用query查询，一个采用header，因为我们进行身份认证，必须将token放在header中，如果你没有，去掉就好了，这里的参数根据你实际项目需要进行定义。

4、最后定义post方法，也可以是get、put等等，根据实际情况定义。

# 这里是之前在schema_view.py中定义好的通用方法，引入进来 
from app.schema_view import DocParam

'''
    测试
'''
class CustomView(APIView):
    '''
    post:
        测试测试测试
    '''
    coreapi_fields = (
        DocParam(name="id",location='query',description='测试接口'),
        DocParam(name="AUTHORIZATION", location='header', description='token'),
    )

    def post(self, request):
        print(request.query_params.get('id'));
        return JsonResponse({'message':'成功！'})


           

5、接收参数这块一定要注意，我定义了一个公用的方法，这里不做过多阐述，如实际过程遇到应用接口与swagger调用接口的传值问题，可参考如下代码。

def getparam(attr,request):
    obj = request.POST.get(attr);
    if obj is None:
        obj = request.query_params.get(attr);
    return obj;
           

修改url.py

针对上一步中定义的测试接口，我们做如下配置。

from django.contrib import admin
from rest_framework import routers
from django.conf.urls import url,include

# 下面是刚才自定义的schema
from app.schema_view import SwaggerSchemaView
# 自定义接口
from app.recommend import CustomView

router = routers.DefaultRouter()

urlpatterns = [
    # swagger接口文档路由
    url(r"^docs/$", SwaggerSchemaView.as_view()),
    url(r'^admin/', admin.site.urls),
    url(r'^', include(router.urls)),
    # drf登录
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))

    # 测试接口
    url(r'^test1', CustomView.as_view(), name='test1'),
]

           

效果展示

访问地址：http://localhost:8001/docs/

总结

django-rest-swagger版本大于2的时候，不再支持yaml注释方式。django-rest-swagger本身只有你的路径中含有参数的时候，才能自动获取参数。很多时候我们不希望我们的参数出现在路径中，因此只能自定义。