drf-接口文档

接口文档

　　前端需要使用我们写的接口（移动端，Web、桌面端），我们后端要写一个接口文档，去详细记录接口的相关信息。

1. 接口文档的展现形式：

　　1. word，md：写好传到公司的某个平台，前端可以下载

　　2. 自动生成接口文档：后端通过配置，把所写的接口都自动生成，通过访问生成的地址就能看到所有的接口文档

　　3. 公司内部搭建接口文档平台

　　　　- 开源：Yapi 

　　　　- 自己开发（自研）

　　4. 使用第三方平台（花钱）：showdoc等

2. 接口文档的编写规范：

　以用户注册接口为例：

　　1. 接口描述

　　2. 请求地址

　　3. 请求方式

　　4. 编码格式：json，urlencoded，form-data

　　5. 请求参数：写参数的详解

　　　　- 请求地址参数

　　　　- 请求体参数

　　6. 返回格式示例：要有返回参数说明

　　7. 备注（可有可无）：写错误码的

二、自动生成接口文档

REST framework可以自动帮助我们生成接口文档。

接口文档以网页的方式呈现。

自动接口文档能生成的是继承自APIView及其子类的视图。

1. 使用步骤

1. REST framewrok生成接口文档需要coreapi库的支持：pip install coreapi

2. 设置接口文档的访问路径，在urls文件中配置：

　　在总路由中添加接口文档路径，文档路由对应的视图配置为：rest_framework.documentation.include_docs_urls，参数title：是接口文档网站的标题。

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

　　-1. 单一方法的视图，可以在视图中，加注释，如：

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

 4. 在配置文件中配置

2. 访问接口文档网页

浏览器访问设置的路由地址，即可看到自动生成的接口文档