django中的DRF框架的coreapi和swagger自动生成接口文档

一、第一种文档：coreapi

REST框架可以⾃动帮助我们⽣成接⼝⽂档。

⾃动接⼝⽂档能⽣成的是继承⾃APIView及其⼦类的视图。

1.安装依赖

pip install coreapi

2.在settings配置DEFAULT_SCHEMA_CLASS

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

3.设置接⼝⽂档访问路径

        在总路由中添加接⼝⽂档路径。

from rest_framework.documentation import include_docs_urls

urlpatterns = [
     path('docs/', include_docs_urls(title='My API title')),  # coreapi接口文档
]

4.⽂档描述说明的定义位置

1）单⼀⽅法的视图，可直接使⽤类视图的⽂档字符串，如

 2）包含多个⽅法的视图，在类视图的⽂档字符串中，分开⽅法定义，如

 3）对于视图集ViewSet，仍在类视图的文档字符串中分开定义，但是应使用action名称区分，如

 5.访问接口文档网页

浏览器访问http://192.168.1.10G8000/docs/，即可看到⾃动⽣成的接⼝⽂档。

两点说明：

        1） 视图集ViewSet中的retrieve名称，在接⼝⽂档⽹站中叫做read

        2）参数的Description需要在模型类或序列化器类的字段中以help_text选项定义，如：

class BookInfo(models.Model):
    bread = models.IntegerField(default=0, verbose_name='阅读量', help_text='阅读量')
    
或
class BookReadSerializer(serializers.ModelSerializer):
    class Meta:
        model = BookInfo
        fields = ('bread', )
        extra_kwargs = {
            'bread': {
                'required': True,
                'help_text': '阅读量'
            }
        }

二、第二种接口文档：swagger

1.安装依赖

pip install drf_yasg

2.在settings配置文件中注册

INSTALLED_APPS = [
    'drf_yasg',  # swagger接口文档
]

3.在主路由中设置接口文档访问路径

from django.urls import re_path
from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi


schema_view = get_schema_view(
   openapi.Info(
      title="接口 API文档",  # 必传
      default_version='v1', # 必传
      description="文档描述",
   ),
   public=True,
   permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
   path('swagger/', schema_view.without_ui(cache_timeout=0), name='schema-json'), #专门访问json格式的swagger接口文档
   path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'), # 网页的接口文档，ui设计是基于swagger的设计
   path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
  # 看到原生的(老的）ui用这个接口
]

在setting中配置，可以让swagger接口文档支持JWT的自动认证

# SWAGGER接口文档支持JWT的自动认证（自动在请求头中加入token)
SWAGGER_SETTINGS={
    # 'PERSIST_AUTH':True,
    'REFETCH_SCHEMA_WITH_AUTH':True,
    'REFETCH_SCHEMA_ON_LOGOUT':True,
    'SECURITY_DEFINITIONS':{
        'JWT':{
            'type':'apiKey',
            'name':'Authorization',
            'in':'header'
        },
    }
}