Restful + Swagger + RestController规范

Restful规范

一、请求方式

请求方式	路径	说明
【GET】	/users	查询用户信息列表
【GET】	/users/1001	查看某个用户信息
【POST】	/users	新建用户信息
【PUT】	/users/1001	更新用户信息(全部字段)
【PATCH】	/users/1001	更新用户信息(部分字段)
【DELETE】	/users/1001	删除用户信息
【PATCH】	/	一般不用，用【PUT】

二、URL规范

URL

1. 通常使用https请求(可以提高数据的安全性)
2. 域名：有api关键字出现

https://api.example.com (存在跨域问题)
https://example.com/api

3. 版本：不同版本需要标注

https://example.com/api/v1 | https://example.com/api/1
https://example.com/api/v2 | https://example.com/api/2

4. 避免层级过深的URI
5. 正斜杠分隔符”/“必须用来指示层级关系
   rul的路径中的正斜杠“/“字符用于指示资源之间的层次关系。

http://api.user.com/schools/grades/classes/boys 学校中所有的男生
http://api.college.com/students/3248234/courses
检索id为3248234的学生学习的所有课程的清单

6. URL结尾不应该包含斜杠“/”
   这是作为URL路径中处理中最重要的规则之一，正斜杠（/）不会增加语义值，且可能导致混淆。REST API不允许一个尾部的斜杠，不应该将它们包含在提供给客户端的链接的结尾处。

7. 应该使用连字符“-”来提高URL的可读性，而不是使用下划线“”
   一些文本查看器为了区分强调URI，常常会在URI下加上下划线。这样下划线“”字符可能被文本查看器中默认的下划线部分地遮蔽或完全隐藏。为避免这种混淆，请使用连字符“-”而不是下划线。

8. URL路径中首选小写字母
   RFC 3986将URI定义为区分大小写，但scheme 和 host components除外。

9. URL中不能有动词
   在Restful架构中，不从请求链接体现操作方式，从请求方式上决定操作方式。每个网址代表的是一种资源，所以网址中不能有动词，只能有名词，动词由HTTP的 get、post、put、delete 四种方法来表示。

get：https://example.com/api/v1/books    获取所有
post：https://example.com/api/v1/books    新增一本
put：https://example.com/api/v1/book/1    更新id=1的一本(整体更新)
patch：https://example.com/api/v1/book/1    更新id=1的一本(局部更新)
delete：https://example.com/api/v1/book/1    删除id=1的一本

10. 资源：请求的目标数据称之为资源，资源一般都由名词复数表示。每个网址代表一种资源（resource），且所用的名词往往与数据库的表格名对应。

https://example.com/api/v1/books (不规范的案例: /get_books/)

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

资源集合：
/library                       //所有图书馆
/library/1/books          //id为1的图书馆中的所有书集 单个资源：
/library/1                    //id为1的图书馆
/library/1;2;3              //id为1，2，3的图书馆

11. 资源过滤：通过接口传递参数来过滤资源 - 筛选、排序、限制

https://example.com/api/v1/books?limit=10    限制10条
…?offset =10    指定返回记录的开始位置
…?page=2&per_page =100    指定第几页，以及每页的记录数
…?sortby=name&order=asc    指定返回结果排序，以及排序顺序
…?animal_type_id=1    指定筛选条件

响应部分

12. 状态码：返回数据要标注状态码，如 {“status”: 200}

SUCCESS(“0”, “查询成功”)
NODATA(“1xx”, “非正确，无数据，显示基本信息”)
FEAILED(“2xx”, “查询失败”)

返回状态码推荐标准HTTP状态码：

200 OK 服务器返回用户请求的数据，该操作是幂等的
201 CREATED 新建或者修改数据成功
204 NOT CONTENT 删除数据成功
400 BAD REQUEST 用户发出的请求有问题，该操作是幂等的
401 Unauthoried 表示用户没有认证，无法进行操作
403 Forbidden 用户访问是被禁止的
422 Unprocesable Entity 当创建一个对象时，发生一个验证错误
500 INTERNAL SERVER ERROR 服务器内部错误，用户将无法判断发出的请求是否成功
503 Service Unavailable 服务不可用状态，多半是因为服务器问题，例如CPU占用率大
…

13. 状态信息:如请求失败需要标注错误信息 {“message”: “请求参数不合法”}

14. 响应数据：请求操作成功的返回结果 {“results”: [数据]}

get：返回资源列表 | 返回单一资源
post：返回单一新增资源
put：返回更新的资源
patch：返回更新的资源
delete：返回空文档

15. 子资源返回资源接口：返回的资源如果有子资源，返回子资源的链接地址，如查找书，书的封面图片就可以url表示

原则

1. 不要相信前端传过来的数据
2. 前端尽量要少传数据

Swagger注解使用说明

第一类：用在类上的注解

第二类：用来对参数进行说明的注解

第三类：用在方法上标记方法的作用

对于注解中的文字描述约定如下：

1. @Api
   例：@Api(tags = “功能模块名称”, description = “描述该功能模块作用”)
   在description 中一定要描述清楚该功能的作用

2. @ApiModel
   例：@ApiModel(value=“实体名称”,description=“实体描述”)
   @ApiModel内的注释不要出现相同，否则会将相同的vo内的字段进行合并

3. @ApiIgnore
   例：

      // 整个类被Swagger忽略
    @ApiIgnore
    @RestController
    @RequestMapping(value = "/xttblog")
    public class XttblogController {}
      
      // 整个方法被忽略
      @ApiIgnore
      public String hello(){
        return "hello";
      }
     
      // Swagger上忽略User参数
      public String sayHello(@ApiIgnore User user){
        return "hello " + user.getName();
      }
   

使用该注解后不会显示对应的接口信息在swagger-ui.html上，对于非提供给前台的类和接口一定要进行忽略。

4. @ApiModelProperty
   例：@ApiModelProperty(value=“属性值名称”,required=true)
   @ApiModelProperty(value=“属性值名称”,hidden=true)
   其中required为是否必填，hidden为是否隐藏，对于不需要前台传入的属性一定要隐藏。

5. @ApiImplicitParam 和 @ApiImplicitParams
   例：@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dataType = “参数类型”)

6. @ApiOperation
   例：@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”)
   其中接口说明中一定要表达清楚该接口的作用，需要前台如何传参、传什么参。

RestController接参说明