🍖drf 自动生成接口文档

一.自动生成接口文档

1.介绍

• REST framework 可以自动帮助我们生成接口文档, 并且接口文档以网页的方式呈现
• 自动接口文档能生成的是继承自APIView及其子类的视图
• 下面介绍两种自动生成接口文档工具 : coreapi、swagger

二.coreapi

1.使用步骤

• 安装 coreapi 依赖库

pip3 install coreapi

• settings.py 配置

REST_FRAMEWORK = {
    # 自动生成接口文档
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

• urls.py 路由配置

# 导入文档路由配置
from rest_framework.documentation import include_docs_urls

# 添加访问路由, 参数 title 为接口网站标题
path('docs/', include_docs_urls(title='接口测试')),

2.文档描述说明的定义位置

• 单一方法的视图, 可以直接使用字符串描述该视图类的功能

class BookListView(generics.ListAPIView):
    """
    返回所有图书信息
    """

• 多个方法的视图, 可以分别对方法进行描述

class BookListCreateView(generics.ListCreateAPIView):
    """
    get:
    返回所有图书信息

    post:
    新建图书
    """

• 对于视图集 ViewSet, 你继承了多少个视图类就书写多少个 action 名称及介绍

class BookView2(ModelViewSet):
    """
       list:
       返回图书列表数据，通过Ordering字段排序

       retrieve:
       返回图书详情数据

       latest:
       返回最新的图书数据

       read:
       查询单个图书接口
       """

3.在网页上进行访问文档

• 通过访问接口文档的路由可以看到结果

• 测试交互 (新增测试)

• 查询所有

4.Description 描述信息的添加

• models.py 的类字段参数 help_text

class Book(models.Model):
    title = models.CharField(max_length=32)
    price = models.IntegerField(help_text='这个是书籍的价格!!')

• 或者在序列化类中通过使用 extra_kwargs 为某字段添加额外的参数

class BookModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = models.Book
        fields = "__all__"
        extra_kwargs = {
            'title': {
                'help_text': '这是书籍的名字!!'
            }
        }

5.报错问题解决

• 抛出 : AttributeError: 'AutoSchema' object has no attribute 'get_link' 错误

# 新版本 drf 默认使用的配置(没有配置就是使用这个)
REST_FRAMEWORK = {
 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.openapi.AutoSchema',
}

# 需要将其改为
REST_FRAMEWORK = {
 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

6.小变化

• 视图集ViewSet中的retrieve名称，在接口文档网站中叫做read

二.swagger

1.使用步骤

• 安装 Swagger 工具

pip install django-rest-swagger

• 在 settings.py 中注册 app

INSTALLED_APPS = [
    'rest_framework_swagger',
]

• 在 urls.py 中添加配置

# 添加 get_schema_view 辅助函数
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer,OpenAPIRenderer

# 参数 title 为接口网站标题
schema_view=get_schema_view(title='测试接口',renderer_classes=[OpenAPIRenderer,SwaggerUIRenderer])

# 添加路由
urlpatterns = [
    # coreapi
    path('docs/', include_docs_urls(title='接口测试')),
    # swagger
    path('docs2/', schema_view, name='docs2'),
]

2.文档描述说明的定义位置

• 与 coreapi 工具中的使用相同

3.测试

• 页面展示

• 功能介绍

• GET 获取所有接口测试

• POST 新增图书测试

4.接口功能描述可以使用 Markdow 语法

• 描述书写示例

class BookView2(ModelViewSet):
    """
       ## list:
       - 返回图书列表数据，通过Ordering字段排序

       ## retrieve:
       - 返回图书详情数据

       ## latest:
       - 返回最新的图书数据

       ## read:
       - 查询单个图书接口

       #### 请求参数
        | 字段名| 含义  | 类型   |
        |:------:|:------:|:------:|
        | title | 书籍名称    |  string |
        | price | 价格    |  int |
       """
    ...

• 效果展示