drf自动生成接口文档

一、介绍

• REST framework可以自动帮助我们生成接口文档
• 接口文档以网页的方式呈现
• 自动接口文档能生成的是继承APIView及其子类的视图

自动生成接口文档有很多种工具，这里我们主要以coreapi、swagger工具为例。

二、coreapi

官网链接：https://github.com/core-api/python-client

1.自动生成接口文档配置

安装：

pip3 install coreapi

配置

• settings.py 配置

# 因为新版的restframework需要指定默认schema
    REST_FRAMEWORK = {
            "DEFAULT_SCHEMA_CLASS": "rest_framework.schemas.AutoSchema",
            # 下面的这个默认的配置使用可能会报错，目前无法解释
            # 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.openapi.AutoSchema',
        }

• urls.py路由配置，一般配置在总路由里面

# 导入文档路由哦配置
from rest_framework.documentation import include_docs_urls
# 添加访问路由，参数title为网站标题
urlpatterns = [
        path('docs/', include_docs_urls(title='测试接口'))
	]

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

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

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

2. 包含多个方法的视图，在类视图的文档字符串中，分开方法定义，如

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

    post:
    新建图书.
    """

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

class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
    """
    list:
    返回图书列表数据

    retrieve:
    返回图书详情数据

    latest:
    返回最新的图书数据

    read:
    修改图书的阅读量
    """

3.访问接口文档网页

浏览器访问 127.0.0.1:8000/docs/，即可看到自动生成的接口文档。

• 测试交互（新增测试）

• 查询所有

4.Description 描述信息的添加

• 在models.py的类字段参数 help_text

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

 

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

class BookSerializers(ModelSerializer):
    class Meta:
        model = models.Book  # 指明该序列化器处理的数据字段从模型类Book参考生成
        fields = "__all__"  # 指明该序列化器包含模型类中的哪些字段，’all‘指明包含所有字段
        extra_kwargs = {
            'title': {
                'help_text': '这是书籍的名字'
            }
        }

 

注意：

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

三、swagger

官网：https://github.com/marcgibbons/django-rest-swagger

安装与配置

1.安装

pip install django-rest-swagger

2.配置

1. 在settings中注册app

INSTALLED_APPS = [
    'rest_framework_swagger',
]

 

2. 在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'),
]

文档描述说明的定义位置

• 与 上面的coreapi 工具中的使用相同

展示

• 页面展示

• 功能介绍

• GET获取所有接口测试

• POST新增图书测试

接口展示描述可以使用Markdown

• 描述书写示例

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

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

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

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

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

• 效果展示