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

规范的事情当然要有专业的工具。推荐使用的是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，支持团队项目管理。

扩展性，从狭义的角度去说，就是程序设计的灵活性,是程序可插拔、组件可重用设计，核心其实是一个程序架构的灵活性。体现的是一个程序员的业务视野，技术积累。

注意：架构的扩展性要求绝大部分情况下并不会直接导致编码量的陡增，就像埋下了伏笔

设计一个会员卡系统，促进用户活跃，提高订单量，最终提高收入。

用户绑定会员，会员拥有权益。

|表名|字段|

|--|--|--|

|用户|id、会员类型|

|会员|id、权益id列表|

|权益|id|

满足当前需求

以上设计满足了最基本的需要，但是扩展性有待商榷

与产品确认第一阶段我们认为的扩展点是否能满足他们后续的要求

综上，会员卡通过卡种则可以满足不同权益的组合，某类型会员卡设有投放条件、也有生效条件，则可以进行定点投放，而权益有多个维度如免费时长、使用地点、投放区域、封顶价格等，运营人员通过组装权益形成的会员卡的投放达到精细化运营的需求

因此进行如下程序设计抽象

只展示核心部分设计

获卡

用卡

如图所示我们将所有获取会员卡的过程抽象成预置筛选器、自定义筛选器、后置筛选器来满足后续多扩展的要求

以上简单的设计支持了运营可能多变的会员卡需求，且编码量并不会陡增，随着项目发展只需要在扩展点进行扩展即可满足业务。

我们说我们不提倡过去设计，但是不代表我们不去做适当的过度设计。 过度设计的把握是

所谓接口能力，即和协同相对。

系统对外开放（所有对外可能性）时应当提供2种能力，即协同能力和接口能力。两者相辅相成。

接口能力：提供对外服务时，以必要的、便捷的，包括文档、平台、少量的人力投入（一般为客服）等形式提供给外部系统接入的接入能力。

最常见的如消息服务供应商提供了短信息服务。

协同能力：提供对外服务时，以必要的人力投入（一般为开发人员）配合接入本系统的能力

对比协同和接口能力，显而易见的接口能力才是我们崇尚和追求的目标

假如你提供的消息推送系统，提供的服务是根据用户传送的内容进行推送到端的服务

那么你的扩展点可以是：

如果你开发的系统架构天然具备这些扩展点那么恭喜你，你只需要简单提供接入文档便可以提供接入能力

所有的抽象都是从设想开始，在设想中，我们通过质疑、猜测、发散思维对业务的可能性、使用技术的可能性进行深入分析。

比如做一套用户登录系统，我们了解到系统的需求是为某一类用户提供登录并保持会话的服务

那么我们可以猜测 这类用户可以通过手机号码、社交账号、注册登录、扫码登录等来登录

这些方式其实很笼统，我们可以进行整理

手机号码是一个用户的标识、而社交账号是一类账号、注册登录也是一类账号、扫码登录是登录的形式，这些不一致的概念混杂在一起我们不好分析，所以我们做以下的归类和抽象

我们从登录开始发散到如下结构

因此我们已经开始设想了，这个时候我们架构已经清晰。但是这个架构中的所有组成成员是否都需要？我们要进行第二个阶段剪枝处理。

剪枝来源于我们的产品需求和后续产品设想（因此一个好的产品经理很重要）

我们需要去询问产品经理刚刚的设想哪些是可能的，这个时候需要一个优秀的产品经理。

根据与产品经理的反复确认，我们明白了往我们架构里填充的实际内容是什么，比如

good luck man！

硬件中的“接口”概念--------------------------

硬件接口即I/O设备适配器，具体指CPU和主存、外围设备之间通过总线进行连接的逻辑部件。

接口部件在它动态连接的两个部件之间起着“转换器”的作用，以便实现彼此之间的信息传送。

为了使所有的外围设备能够兼容，并能在一起正确地工作，CPU规定了不同的信息传送控制方法。 一个标准接口可能连接一个设备，也可能连接多个设备。

典型的接口通常具有如下功能：

1.控制

接口靠程序的指令信息来控制外围设备的动作，如启动、关闭设备等。

2.缓冲

接口在外围设备和计算机系统其他部件之间用作为一个缓冲器，以补偿各种设备在速度上的差异。

3.状态

接口监视外围设备的工作状态并保存状态信息。状态信息包括数据“准备就绪”、“忙”、“错误”等等，供CPU询问外围设备时进行分析之用。

4.转换

接口可以完成任何要求的数据转换，例如并－－串转换或串－－并转换，因此数据能在外围设备和CPU之间正确地进行传送。

5.整理

接口可以完成一些特别的功能，例如在需要时可以修改字计数器或当前内存地址寄存器。

6.程序中断

每当外围设备向CPU请求某种动作时，接口即发生一个中断请求信号到CPU。

事实上，一个适配器必有两个接口：

一是和系统总线的接口，CPU和适配器的数据交换一定的是并行方式；

二是和外设的接口，适配器和外设的数据交换可能是并行方式，也可能是串行方式。根据外围设备供求串行数据或并行数据的方式不同，适配器分为串行数据接口和并行数据接口两大类。

编程中的“接口”概念--------------------------

编程中所谓的接口，实际上也是一个类，只是在接口中声明了一组常量和方法，但事实上没有实现任何方法。这有点类似抽象类，接口需要其他类来提供实现自己所定义方法的过程，而不是自己提供。

这里的用接口实现多继承实际上就是可以用类来实现多个接口中的方法。

---