接口文档设计思路

什么是接口文档？

在项目开发中，web项目的前后端分离开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。

为什么要写接口文档？

1、项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发
2、项目维护中或者项目人员更迭，方便后期人员查看、维护

设计原则

1. 充分理由:不是随便一个功能就要有个接口，也不是随便一个需求就要加个接口。每新建一个接口，就要有充分的理由和考虑，无意义的接口不仅增加了维护的难度，更重要是对于程序的可控性的大大降低，接口也会十分臃肿。
2. 职责明确:一个接口只负责一个业务功能，比如查询会员，但不要在查询会员的同时还有修改权限等类似的其他业务功能，应该分成两个接口做。
3. 高内聚低耦合:一个接口要包含完整的业务功能，而不同接口之间的业务关联要尽可能的小。
4. 分析角度明确:设计接口分析的角度要统一明确。否则会造成接口结构的混乱。
5. 入参格式统一:所有接口的参数格式要求及风格要统一，不要一个接口参数是逗号分隔，另一个就是数组;不要一个接口日期参数是x年x月x日风格，另一个就是x-x-x。
6. 状态及消息:提供必要的接口调用状态信息。调用是否成功?如果失败，那么失败的原因是什么。这些必要的信息必须要告诉给客户端。
7. 控制数据量:一个接口返回不应该包含过多的数据量，过多的数据量不仅处理复杂，对数据传输的压力也非常大，会导致客户端反应缓慢。过多的数据量很多时候都是接口划分不明确。

常见的几种接口形式

1、HTTP 接口（RESTful）

基于HTTP协议开发的接口现在应用是最为广泛的，这类API使用起来简单明了，因为它是轻量级的、跨平台、跨语言的，但凡是第三方提供的API都会有HTTP版本的接口。
RESTful API也是基于HTTP协议的，只不过RESTful它并不是一种规范，它是一种设计准则，用不同的HTTP动词（GET、POST、DELETE、PUT等）来表达不同的请求。

2、RPC 接口

RPC技术是指远程过程调用，它本质上是一种Client/Server模式，可以像调用本地方法一样去调用远程服务器上的方法，它支持多种协议（如：HTTP、TCP、UDP、自定协议）和多种数据传输方式（如：Json、XML、Binary、Protobuf等）。

3、Web Service 接口

Web Service其实是一种概念，我们可以将以WEB形式提供的服务称为Web Service，所以像RESTful、XML-RPC、SOAP等都可以当成是Web Service的一种实现方式。
不过Web Service接口和HTTP接口存在一些细小区别就是，Web Service接口支持更复杂的对象，而HTTP接口更多的就是传输字符串或者JSON文本。

我们这里以RESTful风格的HTTP接口为例

RESTful API

REST 全称：RE presentational State Transfer，英文翻译过来就是“表现层状态转化”

用URL定位资源、用HTTP动词（GET、POST、PUT、DELETE)描述操作

基于REST构建的API就是Restful风格。

接口说明

接口描述

准确描述出 使用者，做什么操作，产生什么影响。

请求地址

请求地址中，我们应该写清楚协议，也就是使用http还是https，有些平台已经是强制只能使用https了，因为更加安全。

URL注意事项

1. 不用大写
2. 用中杠-不用下杠_
3. URI中的名词表示资源集合，使用复数形式

资源集合 vs 单个资源

URI表示资源的两种方式：资源集合、单个资源。

资源集合：

/zoos //所有动物园
/zoos/1/animals //id为1的动物园中的所有动物

单个资源：

/zoos/1 //id为1的动物园

HTTP 与 HTTPS 区别

1. HTTP 明文传输，数据都是未加密的，安全性较差，HTTPS（SSL+HTTP） 数据传输过程是加密的，安全性较好。
2. 使用 HTTPS 协议需要到 CA（Certificate Authority，数字证书认证机构） 申请证书，一般免费证书较少，因而需要一定费用。证书颁发机构如：Symantec、Comodo、GoDaddy 和 GlobalSign 等。
3. HTTP 页面响应速度比 HTTPS 快，主要是因为 HTTP 使用 TCP 三次握手建立连接，客户端和服务器需要交换 3 个包，而 HTTPS除了 TCP 的三个包，还要加上 ssl 握手需要的 9 个包，所以一共是 12 个包。
4. http 和 https 使用的是完全不同的连接方式，用的端口也不一样，前者是 80，后者是 443。
5. HTTPS 其实就是建构在 SSL/TLS 之上的 HTTP 协议，所以，要比较 HTTPS 比 HTTP 要更耗费服务器资源。

请求方式

请求方法有很多同，但是最常用的是GET,POST，如果使用 RESTful 规范，还会使用到等其他请求方法。

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。

请求头

请求头通常用来传递一些公用的参数，比如Content-Type,Accept,Cookie,Authorization等。

公共参数

以下三种参数是我们需要明确的

Authorization 是否需要认证
Accept 代表客户端希望接受的数据类型 一般是json
Content-Type 代表发送端（客户端|服务器）发送的实体数据的数据类型 一般是json

字符编码

均使用UTF-8编码

参数说明

请求参数

Parameter Name	Required	Type(length)	Format	Description(EN)	Description	Sample
字段	是否必填	类型(最大长度)	格式	英文说明	说明	例子

类型是属性类型，只有String、Number、Object、Array四种类型；

响应参数

Parameter Name	Type	Format	Description(EN)	Description	Sample
字段	类型	格式	英文说明	说明	例子

状态码参考

约定大于配置，配置大于编码

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

SAMPLE

Request URL

https://{domain}/serviceName/v1/admin/sorting

Request Body

{
  	"Id": 1,
    "sortingResult": "A",
    "sortingMemo": "第一次分类"
}

Response Body

//成功输出示例
{
  "Response": {
    "Status": "200",
    "ErrorCode": 0,
    "ErrorMessage": NULL,
    "Data": {
        
    }
  }
}
//失败输出示例
{
  "Response": {
    "Status": "400",
    "ErrorCode": "e.cmm.5000",
    "ErrorMessage": "Validation error.",
    "Data": {
        
    }
  }
}