接口文档规范

什么是接口

接口全称是应用程序编程接口，是应用程序重要的组成部分。接口可以是一个功能，例如天气查询，短信群发等，接口也可以是一个模块，例如登录验证。接口通过发送请求参数至接口url，经过后台代码处理后，返回所需的结果。

为什么需要编写接口文档

由于接口所包含的内容比较细，在项目中常常需要使用接口文档。研发人员可以根据接口文档进行开发、协作，测试人员可以根据接口文档进行测试，系统也需要参照接口文档进行维护等。

接口文档规范

接口文档内容可大致分为请求前、请求后内容。
请求前的内容包括接口的基本信息。内容如下：
1、接口协议。如http、https、tcp协议等。
2、接口请求方式。常见的请求方式有get、post，还有put、delete等。
3、接口url。接口请求的url
4、接口名称。用于识别接口。
5、接口请求头部。包含请求头部参数、参数说明。
6、接口请求体。包含请求参数、参数说明，与参数格式。
7、

请求后的内容包括接口响应后的结果。内容如下：
1、响应结果。包括返回头部、返回结果参数，参数值说明，参数类型。
2、示例。成功示例与失败示例，与对应的状态码，例如成功返回状态码200。
3、

以上是接口文档必要的基本信息，在项目中为了方便问题追溯与后期维护，接口文档还需要记录接口状态、版本、负责人、创建人、最后编辑人、时间、接口说明等信息。最终一份完善的api文档如下所示。

接口文档编写需要花费一定的精力，随着项目不断更新，接口文档也逐渐成为项目的核心文件。写好接口文档是应用程序发展的基础。
演示工具为Eolinker，使用地址：www.eolinker.com