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时，可填 参数例子
'''
