程序员怎样规范编写接口文档

规范的事情当然要有专业的工具。推荐使用的是docway 写接口文档，方便保存和共春旅享，支持导出PDF MARKDOWN，支持团队项目管理。

一些刚开始写接口文档的服务端同学，很容易按着代码的思路去编写接口文档，这让客户端同学或者是服务对接方技术人员经常吐槽，看不懂接口文档。这篇文章提供一个常规接口文档的编写方法，给大家参考。

一、请求参数

1. 请求方法

GET

用于获取数据

POST

用于更新数据，可与PUT互换，语义上PUT支持幂等

PUT

用于新增数据，可与POST互换，语义上PUT支持幂等

DELETE

用于删除数据

其他

其他的请求方法在一般的接口中很少使用。如：PATCH HEAD OPTIONS

2. URL

url表示了接口的请求路径。路径中可以包含参数，称为地址参数，如**/user/{id}**，其中id作为一个参数。

3. HTTP Header

HTTP Header用于此次请求的基础信息，在接口文档中以K-V方式展示，其中Content-Type则是一个非常必要的header，它描兆橘述的请求体的数据类型。

常用的content-type：

application/x-www-form-urlencoded

请求参数使用“&”符号连接。

application/json

内容为json格式

application/xml

内容为xml格式

multipart/form-data

内容为多个数据组成，有分隔符隔开

4. HTTP Body

描述http body，依赖于body中具体的数据类型。如果body中的数据是对象类型。则需要描述对象中字段的名称、类型、长度、不能为空、默认值、说明。以表格的方式来表达最好。

示例：

二、响应参数

1. 响应 HTTP Body

响应body同请求扒猜凳body一样，需要描述请清除数据的类型。

另外，如果服务会根据不同的http status code 返回不同的数据结构， 也需要针对不同的http status code对内容进行描述。

三、接口说明

说明接口的应用场景，特别的注意点，比如，接口是否幂等、处理是同步方式还是异步方式等。

四、示例

上个示例（重点都用红笔圈出来，记牢了）：

五、接口工具

推荐使用的是http://docway.net（以前叫小幺鸡） 写接口文档，方便保存和共享，支持导出PDF MARKDOWN，支持团队项目管理。

视频版本 在 B站【我是程序汪】

另一个口罩项目的案例，他是蓝牙直接跟硬件对接，本项目是通过MQTT中转对接硬件

程序汪8万接的共享口罩项目，开发周期1个月

项目构成

安装命令

疫情的原因导致口罩需求一直很旺盛，甲方爸爸打算开发一套口罩售卖机器（类似自助售卖机），这种项目其实也不新鲜了，程序汪以前就接到过这种口罩项目，别问我这个项目的意义啊，拿钱干活（程序汪属于干活型），整个口罩项目，我们只做软件部分，硬件和APP部分是另外的团队开发的，这是一个部分外包的项目

程序汪8万接的共享口罩项目，开发周期1个月

APP扫自助售卖机二维码 ->打开H5领取页面 ->如没有领取记录，则选择领取商品的类型（口罩） ->后台接收领取请求 ->发送MQTT请求到服务端 ->MQTT服务端分发请求给售卖机终端 ->对应售卖机接收请求执行指令(出货)

APP甲方提供了，我们只需要把开发好的H5页面 嵌套到APP里即可，一期功能非常简单，可以免费领取一只口罩

本项目其实是基于电商项目的二开，口罩也是一种商品，下单购买一个典型的购物流程，CRUD的功能我就不废话了，主意是和硬件接口的对接，我们采取的方案是利用 Apache Apollo 当MQTT的消息中转站

1.Apollo下载

下载地址：http://activemq.apache.org/apollo/download.html

MQTT是一个基于客户端-服务器的消息发布/订阅传输协议

Apollo是一个多协议代理，支持STOMP，AMQP， MQTT ，Openwire，SSL和WebSockets。就是在服务器端创建一个唯一订阅号，发送者可以向这个订阅号中发东西，然后接受者（即订阅了这个订阅号的人）都会收到这个订阅号发出来的消息。以此来完成消息的推送。服务器其实是一个 消息中转站 。

MQTT接口文档说明

MQ 接口说明书

注意接口罩银消息格式都是json

第三种：报文例子

MQTT口罩接口文档，也分享给大家学习参考下（网盘地址）

硬件部分物伏宴不是程序汪这边负责的，硬件兄弟负责定制烧录，其实这种自动售卖机有市面上已经很多了。

货道式售货机

开源系统上新增了一些CRUD功能

基础对功能都是现成的 比如用户管理 权限 商品 订单等

程序汪接的7个私活都在这里，经验整理

MQTT口罩接口文档，也分享给大家厅旁学习参考下（网盘地址）

原创文章首发 公众号 我是程序汪

https://mp.weixin.qq.com/s/-HiiQ4CW95jFA89kM6-r-w

---