一、安装drf-yasg包
先安装
pip3 install coreapi
再
pip3 install drf-yasg
二、配置
1、在settings中配置
#注册app INSTALLED_APPS = [ .... 'drf_yasg', ... ]#因为我们自定义的认证类,有些接口访问需要使用token,后面就可以在文档中,在请求头中带上token了
SWAGGER_SETTINGS = { 'USE_SESSION_AUTH': True, 'SECURITY_DEFINITIONS': { 'Token': { 'type': 'apiKey', # 'name': 'Authorization', 'in': 'header' }, }, }# 认证使用自己定义的认证类(不属于drf-yasg的配置,只是说明上面配置的token是为解决自定义认证存在的403问题) REST_FRAMEWORK = { 'DEFAULT_AUTHENTICATION_CLASSES': [ # 自己写的认证类 'studentSystemt.apps.user.authen.MyJWTAuthentication' ], }
2、在urls中配置
from drf_yasg.views import get_schema_view
from drf_yasg import openapischema_view = get_schema_view(
openapi.Info(
title="API接口文档平台", # 必传
default_version='v1', # 必传
description="这是一个接口文档",
terms_of_service="http://api.zengsijiu.site",
contact=openapi.Contact(email="yueyueniao@qq.com"),
license=openapi.License(name="BSD License"),
),
public=True,
# permission_classes=(permissions.AllowAny,), # 权限类
)
urlpatterns = [
path('swagger/', 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'),]
三、写模型类
id = models.AutoField(primary_key=True) name = models.CharField(max_length=20,verbose_name='书名',help_text='书名') price = models.DecimalField(max_digits=10,decimal_places=2,verbose_name='价格',help_text='价格')#这里的help_text就是给文档中对该字段的注释,
#所以,最好对每一个字段都加上help_text参数,给字段加上合适的注释
四、写视图类
#方式一:通过视图集,没有手动写视图函数的,写上注释后,对于该类生成的所有的视图函数都是同一个注释的 class BooKGenericaView(GenericViewSet, ListModelMixin, CreateModelMixin): ''' :param : get: 获取数据库中所有的书的信息 :param: post: 新建一本书导数数据库中,可以先通过对publish的get方法获取出版社的id name 书名、publish(外键,输入id) 出版社、price 价格 ''' serializer_class = serializer.BookGenericViewSetSerializer queryset = models.Book.objects.all()#方式二:所有视图函数都是自己手写的,在每个视图都进行了注释
class BooKGenericViewSetPK(GenericViewSet,RetrieveModelMixin,DestroyModelMixin,UpdateModelMixin): serializer_class = serializer.BookGenericViewSetSerializer queryset = models.Book.objects.all() def retrieve(self, request, *args, **kwargs): ''' :param 获取指定书籍的信息,/book/id/ get ''' return super().retrieve(request,*args,**kwargs) def update(self, request, *args, **kwargs): ''' :param 更新指定书的数据 /book/id/ patch方法 ''' return super().update(request,*args,**kwargs) def destroy(self, request, *args, **kwargs): ''' :param 删除指定的书籍 /book/id/ delete ''' return super().destroy(request,*args,**kwargs)
方式一:在每个视图函数中都写着一样的注释
方式二:在手动写视图函数,给函数写注释,不同路由下显示特定的注释