新猿0基础python教程 如何写好接口文档

跟老刘学python 2021-10-27 15:53:29
编程语言 Python 异常处理 开发者 数据

同学们学习python的时候接口文档是比较重要的,接口文档的问题直接影响到我们后续接口的调用以及使用,那么下面我们一起来认真学习下如何写好接口文档。

1 HTTP携带信息的方式
  • url
  • headers
  • body: 包括请求体,响应体
2 分离通用信息

一般来说,headers里的信息都是通用的,可以提前说明,作为默认参数

3 路径中的参数表达式

URL中参数表达式使用[​ ​mustache​​​的形式,参数包裹在双大括号之中​​{{paramName}}​​例如:

  • ​/api/user/{{userId}}​
  • ​/api/user/{{userType}}?age={{age}}&gender={{gender}}​
4 数据模型定义

数据模型定义包括:

  • 路径与查询字符串参数模型
  • 请求体参数模型
  • 响应体参数模型

数据模型的最小数据集:

  • 名称
  • 是否必须
  • 说明

“最小数据集”(MDS)是指通过收集最少的数据,较好地掌握一个研究对象所具有的特点或一件事情、一份工作所处的状态,其核心是针对被观察的对象建立起一套精简实用的数据指标。最小数据集的概念起源于美国的医疗领域。最小数据集的产生源于信息交换的需要,就好比上下级质量技术监督部门之间、企业与质量技术监督部门之间、质量技术监督部门与社会公众之间都存在着信息交换的需求。

一些文档里可能会加入字段的类型,但是我认为这是没必要的。以为HTTP传输的数据往往都需要序列化,大部分数据类型都是字符串。一些特殊的类型,例如枚举类型的字符串,可以在说明里描述。另外:​ ​数据模型非常建议使用表格来表现​​。举个栗子?:


名称

是否必须

说明

userType

用户类型。​​commom​​​表示普通用户,​​vip​​表示vip用户

age

用户年龄

| gender | 否 | 用户性别。​​1​​​表示男,​​0​​表示女 |

5 请求示例
// general
POST http://www.testapi.com/api/user
// request payload
{
"name": "qianxun",
"age": 14,
"like": ["music", "reading"],
"userType": "vip"
}
// response
{
"id": "asdkfjalsdkf"
}
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.
  • 10.
  • 11.
  • 12.
  • 13.
6 异常处理

异常处理最小数据集

  • 状态码
  • 说明
  • 解决方案

举个栗子?:

状态码

说明

解决方案

401

用户名密码错误

检查用户名密码是否正确

424

超过最大在线数量

请在控制台修改最大在线数量

之前我一直不想把解决方案加入异常处理的最小数据集,但是对于很多开发者来说,即使它知道​​424​​​代表​​超过最大在线数量​​。如果你不告诉如果解决这个问题,那么他们可能就会直接来问你。所以最好能够一步到位,直接告诉他应该如何解决,这样省时省力。

7 如何组织?

7.1 一个创建用户的例子:创建用户

1 请求示例

// general
POST http://www.testapi.com/api/user/vip/?token=abcdefg
// request payload
{
"name": "qianxun",
"age": 14,
"like": ["music", "reading"]
}
// response
{
"id": "asdkfjalsdkf"
}
  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.
  • 10.
  • 11.
  • 12.

2 路径与查询字符串参数模型

​POST http://www.testapi.com/api/user/{{userType}}/?token={{token}}​

名称

是否必须

说明

userType

用户类型。​​commom​​​表示普通用户,​​vip​​表示vip用户

token

认证令牌

3 请求体参数模型

名称

是否必须

说明

name

用户名。4-50个字符

age

年龄

like

爱好。最多20个

4 响应体参数模型

名称

说明

id

用户id

5 异常处理

状态码

说明

解决方案

401

token过期

请重新申请token

| 424 | 超过最大在创建人数 | 请在控制台修改最大创建人数 |

7.2 这样组织的原因

  1. ​请求示例​​​: 请求示例放在第一位的原因是,要用​​最快的方式​​告诉开发者,这个接口应该如何请求
  2. ​路径与查询字符串参数模型​​​: 使用​​mustache​​包裹参数
  3. ​请求体参数模型​​:如果没有请求体,可以不写
  4. ​响应体参数模型​​:
  5. ​异常处理​
8 文档提供的形式

文档建议由一下两种形式,​​在线文档​​​,​​pdf文档​​。

  • ​在线文档​

- 更新方便 - 易于随时阅读 - 易于查找

  • ​pdf文档​

- 内容表现始终如一,不依赖文档阅读器 - 文档只读,不会被轻易修改 其中由于是面对第三方开发者,​ ​公开的在线文档必须提供​​​;由于某些特殊的原因,可能需要提供文件形式的文档,建议提供pdf文档。当然,以下的文档形式是​​非常不建议​​提供的:

  • word文档
  • markdown文档

word文档和markdown文档有以下缺点:

  • ​文档的表现形式非常依赖文档查看器​​:各个版本的word文档对word的表现形式差异很大,可能在你的电脑上内容表现很好的文档,到别人的电脑上就会一团乱麻;另外markdown文件也是如此。而且markdown中引入文件只能依靠图片链接,如果文档中含有图片,很可能会出现图片丢失的情况。
  • ​文档无法只读​​:文档无法只读,就有可能会被第三方开发者在不经意间修改,那么文档就无法保证其准确性了。

总结一下,文档形式的要点:

  • ​只读性​​:保证文档不会被开发者轻易修改
  • ​一致性​​:保证文档在不同设备,不同文档查看器上内容表现始终如一
  • ​易于版本管理​​​:文档即软件(DAAS: Document as a Software),一般意义上说​​软件 = 数据 + 算法​​​, 但是我认为​​文档也是一种组成软件的重要形式​​。既然软件需要版本管理,文档的版本管理也是比不可少的。
版权声明
本文为[跟老刘学python]所创,转载请带上原文链接,感谢
https://blog.51cto.com/u_15360516/4344800

  1. 【算法学习】237. 删除链表中的节点(java / c / c++ / python / go)
  2. 【算法学习】1672. 最富有客户的资产总量(java / c / c++ / python / go / rust)
  3. 【算法学习】771. 宝石与石头(java / c / c++ / python / go / rust)
  4. 【算法学习】02.03. 删除中间节点(java / c / c++ / python / go)
  5. 【算法学习】1769. 移动所有球到每个盒子所需的最小操作数(java / c / c++ / python / go / rust)
  6. 【算法学习】1486. 数组异或操作(java / c / c++ / python / go / rust)
  7. 【算法学习】LCP 44. 开幕式焰火(java / c / c++ / python / go / rust)
  8. 【算法学习】剑指 Offer 58 - II. 左旋转字符串(java / c / c++ / python / go / rust)
  9. python的学校疑问难题求解
  10. 大学python题 作业题 基础题
  11. Python字典的知识,输出的样例为,最高分:89
  12. python写入文件失败且程序提前中止
  13. 用Python写一个学生字典,帮帮忙
  14. Python,能不能帮帮忙,真的不会
  15. [python] yield 和 readline() 的使用问题
  16. python安装找不到问题救救孩子
  17. python中循环结构完成数字游戏
  18. 如何用python实现多列vlookup(excle操作)
  19. python语言deLong‘s test:通过统计学的角度来比较两个ROC曲线、检验两个ROC曲线的差异是否具有统计显著性
  20. LPC55S69 MicroPython模组和库函数
  21. LPC55S69 IoT Kit专属 Micropython模组和库函数简介
  22. 安装LPC55S69 MicroPython模块是遇到的CDC Interface驱动问题
  23. 使用soundcard在Python中操作声卡
  24. 自动化快速上手--Python(7)--【字典】--每天半小时
  25. Python之循环结构【包括列表、for语句、range()函数、while语句、循环嵌套、break、continue、算法优化等】
  26. Python模块安装与异常处理详解(numpy、pygame、matplotlib等)
  27. Python__init__.py作用
  28. python 爬取网页时出现多种错误
  29. Python中关于大量绘制速度曲线的问题
  30. python-async的安装和使用方法
  31. Matlab的fread(fild,1,int32)迁移到python变成什么
  32. 想用python开发一个音频过滤器,请指导?
  33. python使用openpyxl读取Excel文件显示No such file or directory
  34. xmoji虚拟头像交互如何使用python(像深度学习)制作?
  35. python 打开页面页面的链接,为什么总是报错呀?
  36. Python中DataLoader的batch_size、shuffle的疑惑。
  37. python安装pymssql库,可以import,但无法调用函数
  38. 【Python学习教程】常用的8个Python数据可视化库!
  39. python处理csv中的时间
  40. 数据结构,元音统计(Python)
  41. python的site-packages复制直接到其他电脑环境上能用吗
  42. Pycharm如何给项目配置python解释器
  43. conda创建python虚拟环境
  44. Python selenium的爬虫无法完整爬取整个页面的内容
  45. 高清版!这18张 Python 数据科学速查表,让你的代码变得更强大!
  46. python代码不会敲,请好心老哥帮助我一下
  47. Python敲七输出符合的个数
  48. Python 有人能给提供简单的思路嘛
  49. python单次运行写入csv成功,循环写入失败
  50. python利用os模块进行增量备份
  51. 【算法学习】807. 保持城市天际线(java / c / c++ / python / go / rust)
  52. 如何利用python输出等腰杨辉三角
  53. python按键执行倒计时小程序不能实现要求,要怎么改才好?
  54. Python request模块post请求的问题
  55. Django连接已有Oracle时的主键设置问题,没主键无法查询怎么办?
  56. 如何用python的dictionary编写一个联系人通讯录程序
  57. 如果Python里range反向输出,不输出步长会怎么样?
  58. 一个关于Python pip的问题: 出现Cannot open \python\Scripts\pip-script.py报错
  59. 富婆闺蜜非让我用Python给她写个淘宝双十一抢购脚本,那只能安排了
  60. 【全网最全】python正则表达式大全,所有讲解都在这,包教包会,学不会找我!