接口文档编写方法

接口文档

对于前后端分离的项目，我们编写接口前端并不知道我们的 请求地址，请求方式。与需要携带的一些数据或编码格式与返回格式，我们需要编写接口文档来给前端工作人员阅读。

接口文档的编写方式

1. 直接在word，md来编写

可以按照下面的格式编写也可以通过公司里的其他接口文档编写

接口描述：   用户注册
请求URL：    http://xx.com/api/user/register
请求方式：   post
编码方式：   json.urlencoded,form-data
参数：      一些字段的信息是否必选，类型，说明
返回给前端的数据示例：
返回数据字段解释
错误码

2.使用第三方平台，一般都是收费的

https://www.showdoc.com.cn/item/index

3.公司自己使用第三方开源的搭建的-Yapi

说明文档
https://zhuanlan.zhihu.com/p/366025001 

4.使用drf编写的接口，可以自动生成接口文档

drf-yasg 官方推荐使用
coreapi  我们使用这个

coreapi自动生成接口文档

下载模块

pip3.8 install coreapi -i https://pypi.douban.com/simple

配置路由

from rest_framework.documentation import include_docs_urls
path('docs/', include_docs_urls(title='xx项目接口文档'))
路由随便写 只是访问的入口

视图类方法写注释就会显示

单一方法视图类：
class BookView(ListAPIView):
    """
    返回所有图书信息
    """
    
 多个方法视图类
class BookView(ListCreateAPIView):
    """
    get: 
    返回所有图书信息
    post:
    新增图书
    """
视图集类
class BookView(ModelViewSet):
    """
    list:
        返回所有图书
    read:
        返回单个图书
    create:
        新增图书
    update:
        更新图书
    delete:
        删除图书
    """
    queryset = Book.objects.all()
    serializer_class = BookSerializer

在序列化类或模型表中给字段加属性

help_text :字段说明
required  :必填

配置文件

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

    	}

Interact按钮还可提交数据