django使用swagger文档

django使用swagger文档

1.安装swagger

pip install drf-yasg2


在urls.py 中配置建议在总路由中配置
from django.urls import path, include, re_path
from rest_framework import permissions
from drf_yasg2.views import get_schema_view
from drf_yasg2 import openapi

schema_view = get_schema_view(
    openapi.Info(
        title="Tweet API",
        default_version='v1',
        description="Welcome to the world of Tweet",
        terms_of_service="https://www.tweet.org",
        contact=openapi.Contact(email="demo@tweet.org"),
        license=openapi.License(name="Awesome IP"),
    ),
    public=True,
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    # swagger
    re_path(r'^doc(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),  # <-- 这里
    path('doc/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),  # <-- 这里
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),  # <-- 这里
    ##############################################################
]
'''
	配置完成之后可以在 浏览器中访问http://127.0.0.1:8000/doc/访问文档
'''

2.使用装饰器方式描述接口

目前主要用的参数:
    	method:请求方式
        methods:请求方式 ['GET','POST']
       	tags：接口分组，一组的接口会放一起
        operation_description：接口描述，描述接口的作用支持markdowm语法
        operation_summary:接口简单描述，出现在接口列表中的描述，方便接口列表中找到
        request_body:post请求携带的参数
        manual_parameters:GET请求携带的参数 name-参数名 in_-参数位置 description-参数描述 type-参数类型
1.导入装饰器
    from drf_yasg2.utils import swagger_auto_schema
    from drf_yasg2 import openapi
    
2.使用
	（1）
    	class Login(GenericViewSet):
    		queryset = User.objects.all()
    		serializer_class = LoginSerializer
            
            @swagger_auto_schema(tags=['用户登入'], operation_description='用户登入接口', operation_summary='用户登入',
                                 request_body=openapi.Schema(type=openapi.TYPE_OBJECT, properties={
                                     'username': openapi.Schema(type=openapi.TYPE_STRING, description='字符串', title='用户名'),
                                     'password': openapi.Schema(type=openapi.TYPE_STRING, description='字符串'),
                                 }))
             def create(self, request:Request)-> APIResponse:
                    '''
                        登入
                        :param username: 用户名
                        :param password: 密码
                    '''
                    ....
                    
                    return APIResponse()
           '''
           		当我们继承的是视图集时不需要写method或methods
           '''

(2)
	class Book(GenericViewSet):

    @swagger_auto_schema(operation_description='根据分页返回分页数据',operation_summary='返回对应数据',
                         manual_parameters=[
                             openapi.Parameter(name='page', in_=openapi.IN_QUERY, description='页数', type=openapi.TYPE_STRING,pattern='1'),
                   			openapi.Parameter(name='row', in_=openapi.IN_QUERY, description='一页的数据条数', type=openapi.TYPE_STRING)])
    def list(self, request):
		''''''
        return APIResponse()
    
    '''
    manual_parameters描述GET请求参数
    name --- 参数名称
    in_ --- 参数位置 
    		openapi.IN_QUERY "query" http://127.0.0.1:8000/api/v1/..../?page=1&row1  放在url中
    		openapi.IN_FORM "formData" 
    		openapi.IN_BODY "body"
    		openapi.IN_PATH "path"
    		openapi.IN_HEADER "header"
    		剩下的还没试，可自行尝试
    description --- 参数描述
    type --- 参数类型 
    		openapi.TYPE_STRING "string"
    		openapi.TYPE_OBJECT "object"
    		openapi.TYPE_ARRAY "array"
    		openapi.TYPE_FILE "file"
    		openapi.TYPE_NUMBER "number"
    		openapi.TYPE_BOOLEAM "boolean"
    		openapi.TYPE_INTEGER "integer"
    pattern --- 当type为openapi.TYPE_STRING时，可填 参数例子
    '''