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

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

# 1 HTTP携带信息的方式

- url

- headers

- body: 包括请求体，响应体

# 2 分离通用信息

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

# 3 路径中的参数表达式

URL中参数表达式使用[mustache](https://github.com/janl/mustache.js)的形式，参数包裹在双大括号之中`{ {paramName}}`

例如：

- `/api/user/{ {userId}}`

- `/api/user/{ {userType}}?age={ {age}}&gender={ {gender}}`

# 4 数据模型定义

数据模型定义包括：

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

- 请求体参数模型

- 响应体参数模型

数据模型的最小数据集：

- 名称

- 是否必须

- 说明

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

一些文档里可能会加