自动生成文档接口

一、自动生成接口文档

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

1、安装依赖

pip3 install coreapi

2、设置接口文档访问路径

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    url('docs/', include_docs_urls(title='API接口文档')),
]

3、文档描述说明的定义位置

①单一方法的视图，可直接使用类视图的文档字符串，如

class Test(APIView):
    """
    返回所有图书信息.
    """

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

class Test(APIView):
    """
    get:
    返回所有图书信息.
    post:
    新建图书.
    """

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

class Publish(ModelViewSet):
    """
    get:
    返回图书列表数据

    post:
    创建图书数据

    delete:
    删除图书数据

    retrieve:
    修改图书数据
    """
    queryset = models.Publish.objects.all()
    serializer_class = PublishSerializers

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

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

class Publish(models.Model):
    name = models.CharField(max_length=32, help_text='名字')
    city = models.CharField(max_length=64, help_text='城市')

或者

class PublishSerializer(serializers.ModelSerializer):
    class Meta:
        model = Publish
        fields = "__all__"
        extra_kwargs = {
            'name': {
                'required': True,
                'help_text': '名字'
            }
        }

接口文档展示

二、typing模块

提高代码健壮性，限制返回值类型的

1、前言

Python是一门弱类型的语言，很多时候我们可能不清楚函数参数类型或者返回值类型，很有可能导致一些类型没有指定方法，在写完代码一段时间后回过头看代码，很可能忘记了自己写的函数需要传什么参数，返回什么类型的结果，就不得不去阅读代码的具体内容，降低了阅读的速度，typing模块可以很好的解决这个问题。

2、typing模块的作用

类型检查，防止运行时出现参数和返回值类型不符合。
作为开发文档附加说明，方便使用者调用时传入和返回参数类型。
该模块加入后并不会影响程序的运行，不会报正式的错误，只有提醒。

# 注意：typing模块只有在python3.5以上的版本中才可以使用,pycharm目前支持typing检查

3、typing模块的常用方式

from typing import List, Tuple, Dict

def test(a: int, string: str, f: float, b: bool) -> Tuple[List, Tuple, Dict, bool]:
    ll=[1,2,3,4]
    tup = (string, a, string)
    dic = {"xxx": f}
    boo = b
    return ll, tup, dic, boo

print(test(12, "lqz", 2.3, False))

注意：
    在传入参数时通过'参数名：类型'的形式声明参数的类型；
    返回结果通过'-> 结果类型'的形式声明结果的类型。
    在调用的时候如果参数的类型不正确pycharm会有提醒，但不会影响程序的运行。
    对于如list列表等，还可以规定得更加具体一些，如：'-> List[str]',规定返回的是列表，并且元素是字符串。