怎样写好接口文档 内容概要 写接口文档的四种方式 DRF 自动生成接口文档步骤（coreapi） 接口文档组成 内容详细 写接口文档的四种方式 目前流行的前后端分离模式，在前后端进行数据交互之前，后端需要把数据交互的接口的作用、地址、格式等信息提供给前端，需要我们书写标准的接口文档，以便与前端进行数据交互。 使用word或者md文档编写，自己纯手写 第三方平台录入数据，固定的位置填固定的东西 公司自己开发接口平台，搭建接口平台 自动生成接口文档：coreapi，swagger 也可以直接把 postman 的测试接口集合导出成文件，发送给前端 
参考接口文档： https://open.weibo.com/wiki/2/users/show https://www.cnblogs.com/noteaddr/p/12971759.html https://zhuanlan.zhihu.com/p/366025001 DRF 自动生成接口文档步骤（coreapi） 1、安装 ： 2、书写路由： 参数为接口文档网站的标题 3、写好视图层类 4、项目下的配置文件 settings.py 配置 ： 5、访问地址： http://127.0.0.1:8000/docs/ 6、给前端，前端按照这个接口文档开发 7、基于这个，录入到第三方接口平台，自己写word文档 
文档描述说明的定义位置# 1） 单一方法的视图，可直接使用类视图的文档字符串，如 2）包含多个方法的视图，在类视图的文档字符串中，分开方法定义，如 3）对于视图集ViewSet，仍在类视图的文档字符串中分开定义，但是应使用action名称区分，如 写视图类，只需要加注释即可 1） 视图集ViewSet中的retrieve名称，在接口文档网站中叫做read 2）参数的Description需要在模型类或序列化器类的字段中以help_text选项定义，如： 或 接口文档组成 1 HTTP携带信息的方式 url headers body: 包括请求体，响应体 2 分离通用信息 一般来说，headers里的信息都是通用的，可以提前说明，作为默认参数 3 路径中的参数表达式 URL中参数表达式使用mustache的形式，参数包裹在双大括号之中“ 例如： 4 数据模型定义 数据模型定义包括： 路径与查询字符串参数模型 请求体参数模型 响应体参数模型 数据模型的最小数据集： 名称 是否必须 说明 “最小数据集”（MDS）是指通过收集最少的数据，较好地掌握一个研究对象所具有的特点或一件事情、一份工作所处的状态，其核心是针对被观察的对象建立起一套精简实用的数据指标。最小数据集的概念起源于美国的医疗领域。最小数据集的产生源于信息交换的需要，就好比上下级质量技术监督部门之间、企业与质量技术监督部门之间、质量技术监督部门与社会公众之间都存在着信息交换的需求。 一些文档里可能会加入字段的类型，但是我认为这是没必要的。以为HTTP传输的数据往往都需要序列化，大部分数据类型都是字符串。一些特殊的类型，例如枚举类型的字符串，可以在说明里描述。 另外：。 举个栗子?： 名称 是否必须 说明 userType 是 用户类型。表示普通用户，表示vip用户 age 否 用户年龄 gender 否 用户性别。表示男，表示女 5 请求示例 6 异常处理 异常处理最小数据集 状态码 说明 解决方案 举个栗子?： 状态码 说明 解决方案 401 用户名密码错误 检查用户名密码是否正确 424 超过最大在线数量 请在控制台修改最大在线数量 之前我一直不想把解决方案加入异常处理的最小数据集，但是对于很多开发者来说，即使它知道代表。如果你不告诉如果解决这个问题，那么他们可能就会直接来问你。所以最好能够一步到位，直接告诉他应该如何解决，这样省时省力。 7 如何组织？ 7.1 一个创建用户的例子：创建用户 1 请求示例 2 路径与查询字符串参数模型 名称 是否必须 说明 userType 是 用户类型。表示普通用户，表示vip用户 token 是 认证令牌 3 请求体参数模型 名称 是否必须 说明 name 是 用户名。4-50个字符 age 否 年龄 like 否 爱好。最多20个 4 响应体参数模型 名称 说明 id 用户id 5 异常处理 状态码 说明 解决方案 401 token过期 请重新申请token 424 超过最大在创建人数 请在控制台修改最大创建人数 7.2 这样组织的原因 : 请求示例放在第一位的原因是，要用告诉开发者，这个接口应该如何请求 ： 使用包裹参数 ：如果没有请求体，可以不写 ： 8 文档提供的形式 文档建议由一下两种形式，，。 更新方便 易于随时阅读 易于查找 内容表现始终如一，不依赖文档阅读器 文档只读，不会被轻易修改 其中由于是面对第三方开发者，；由于某些特殊的原因，可能需要提供文件形式的文档，建议提供pdf文档。当然，以下的文档形式是提供的： word文档 markdown文档 word文档和markdown文档有以下缺点： ：各个版本的word文档对word的表现形式差异很大，可能在你的电脑上内容表现很好的文档，到别人的电脑上就会一团乱麻；另外markdown文件也是如此。而且markdown中引入文件只能依靠图片链接，如果文档中含有图片，很可能会出现图片丢失的情况。 ：文档无法只读，就有可能会被第三方开发者在不经意间修改，那么文档就无法保证其准确性了。 总结一下，文档形式的要点： ：保证文档不会被开发者轻易修改 ：保证文档在不同设备，不同文档查看器上内容表现始终如一 ：文档即软件（DAAS: Document as a Software），一般意义上说, 但是我认为。既然软件需要版本管理，文档的版本管理也是比不可少的。
2024最新激活全家桶教程，稳定运行到2099年，请移步至置顶文章：https://sigusoft.com/99576.html
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容， 请联系我们举报，一经查实，本站将立刻删除。 文章由激活谷谷主-小谷整理,转载请注明出处：https://sigusoft.com/79004.html
