Restful风格的接口以及接口文档书写规范

Restful风格的接口以及接口文档书写规范

一、接口规范

1. 接口描述：简要说明接口的功能、业务等。
2. 权限说明：如果接口调用需要授权认证，在这部分进行说明。
	比如token的获取方式，怎么才能获取授权。
3. 接口详细：
	- 请求方式：新增(post) 修改(put) 删除(delete) 获取(get)
	- 请求地址：接口的调用地址
		如：http://XXXX:XX/system/type
	- 请求数据：
		1.参数列表：参数类型，参数名称，是否必填，参数描述
		2.请求数据整体格式，如ajax请求一般是json。
		3.请求数据示例
		4.编码格式 utf-8等
	- 返回数据：
		1.参数列表：参数类型，参数名称，是否必填，参数描述
		2.返回数据整体格式，如ajax请求一般是json。
		3.返回数据示例：包括三部分，code接口状态码、message调用信息、data接口返回数据
		4.编码格式 utf-8等
4. 其他：说明一些其他内容，注意点等。

二、Restful接口

URL 的意思是统一资源定位符。
这里已经清晰的表明，一个 URL 应该用来定位资源，而不应该掺入对操作行为的描述。

1. API带版本控制，比如v1,v2
2. URL 中不应该出现任何表示操作的动词，链接只用于对应资源。
	如get、search、delete、create等
3. URL 中应该单复数区分。
	比如GET操作，/api/vi/users表示获取所有用户列表；
	如果获取单个资源，传入 ID，比如/api/users/123表示获取id为123的用户的信息。
4. 使用HTTP自身的方法区分增删改查资源。 
	GET：查询，POST：新增，PUT：更新，DELETE：删除
5. 状态码：常见的有：
	- 200 [GET] 只读 成功
	- 201 created – [POST/PUT/PATCH] 新增、修改
	- 400 INVALID REQUEST – [POST/PUT/PATCH]  非法请求
	- 404 NOT FOUND – [*] 资源不存在
	- 401 表示用户身份认证失败(没有系统或者接口权限，认证失败)
	- 403 表示你验证身份通过了，但是无权限操作资源。(没有具体的资源访问权限)
	- 500 SERVER ERROR – [*] 接口服务错误
6. 授权：OAuth或者token授权，确保接口安全性
	关于OAuth的理解，推荐一篇文章http://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html
7. 过滤器: 减少对资源的限制，方便接口调用，资源更加开放
	如分页limit\offset，排序order by column等可以调用方限制。
8. 推荐使用https协议，更加安全。
9. 返回数据建议使用json格式。

接口示例：

GET	 https://XXXX:XX/api/v1/zoo/list：
	列出所有的动物园；
GET	 https://XXXX:XX/api/v1/zoo/123：
	列出id为123的动物园信息；

三、SpringMVC框架对Restful的支持-常用注解

1. @Controller:声明一个处理请求的控制器
2. @RequestMapping:请求映射地址到对应的方法,该注解又可以分为一下几种类型:
	- @GetMapping	查询
	- @PostMpping	新增
	- @PutMapping	更新
	- @DeleteMapping	删除
	- @PathVariable	获取URL中参数，占位符绑定，和以上注解结合使用
3. @ResponseBody:将方法的返回结果直接写入到HTTP的Response的Body中，通常为json
4. @RequestBody:接受request body中的请求内容，通常为json。
5. @RestController:相当于@ResponseBody ＋ @Controller ；限制了返回的只能是数据，不能是视图。