什么是RESTful，SpringBoot怎么引入丝袜哥（Swagger）

前言

最近在开发自己的博客系统，前端采用vue+nuxt，后端采用SpringBoot作为整体架构，所以用到一些实战的技巧就打算顺便写写文章。

1.了解RESTful

做为一个网络应用开发人，都晓得我们一个软件分为前端与后端，在前后端的交互当中，我们需要制定一个“规约”，这个规约就是我们说的REST；

REST的全称就是表述层状态转移（表述层状态转移），这是一套在互联网体系中，调用者与被调用者进行互动的规约设计，REST其实并不是什么新鲜事物了，早在2000年的时候Roy Thomas Fielding博士就在论文中提及了，Roy Thomas Fielding博士是HTTP1.0与HTTP1.1协议的主要设计者，可以说REST是在HTTP交互当中的最佳规约了。

由于自4G以来的互联网的爆炸性发展，网络应用的爆炸性增长，所以REST规约逐渐被重视了起来，那么说了那么多废话，我们还是来看看这个规约吧。

2.RESTful规范

REST并不是什么新鲜的技术，而是在HTTP在的一种规范，首先HTTP的操作主要有GET、POST、DELETE、PUT;

我们对于后端的操作最最最最常见的，也就是这四个，GET是获取数据的操作，POST是提交数据的，DELETE是删除资源的，PUT是对于资源的更新操作；

我们回想一下：前端与后端的交互当中，不就是通过URL与参数的交互与响应，URL含义是“统一资源定位符”，全称是Uniform Resource Locator，我们重新读一遍这几个字“统一资源定位符”，也就是对于URL来说，只需要关心这个链接是一个资源，而操作应该是停留在HTTP的操作当中：

GET : URL 获取这个资源

DELETE : URL 删除这个资源

POST : URL 对这个资源进行数据的提交

PUT : URL 更新资源

如上的语义就可以很清晰地表达你所要表达的意思了，而不应该在你的URL当中添加对于操作的动词，我见过太多太多的例子是直接getPeople（当然我之前也是这么干的）。对于同一个资源的操作，换了N多的URL。

下面简单举几个简单的示范案例

GET https://www.waibizi.com/apple/list 获取苹果列表

GET https://www.waibizi.com/apple/1 获取编号是1的苹果

PUT https://www.waibizi.com/apple/1 对于编号是1的苹果进行数据的更新

POST https://www.waibizi.com/apple 新增一个苹果

POST https://www.waibizi.com/apple/list 新增几个苹果（当然你的数据应该放在body当中）

DELETE https://www.waibizi.com/apple/list 删除几个苹果

…

这个REST规约并不是那么苛刻的，但是切记不要将动词放到URL当中，要对于路径参数尽可能地运用，并且你的URL声明不应该是又长又无语义化的，REST本意就是为了语义化、增强可读性，而如果你强制为了遵守REST规约，导致可读性变差也是不可取的一种行为。

3.统一返回值封装

对于同一个后端请求，返回数据格式应该是统一的，而不是混乱的。下面是简单的示例，msg是对于操作的提示信息，code是HTTP的状态码，尽量遵守HTTP的状态码，而不是自己去定义一些规范，最后，data才是你实际需要的数据。

4.Swagger介绍

Swagger 是一个RESTful API 工具，我们在做开发的时候，经常会因为接口文档的规范性文档，前后端需要讨论磨合文档规范才可以开发，使用Swagger可以帮助我们统一一个规范要求。在使用Spring或者SpringBoot的时候，运用这个工具，可以很快地生成交互式的接口文档，Swagger由于读音与丝袜哥相似，所以通常也会以丝袜哥称这套工具，Swagger是目前世界上最流行的API表达工具了，尽管目前有新的工具，封装了Swagger更改了UI，但是现在主流还是Swagger。

5.上手Swagger

导入Swagger的依赖包

<!-- swagger文档相关依赖-->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>

创建 SwaggerConfig 配置类

public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()/* 添加你需要被扫描为swagger的相关包路径（通常配置主路径就可以了） */.apis(RequestHandlerSelectors.basePackage("com.waibizi.blog.project")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder()/* 添加swagger的标题 */.title("个人博客")/* 添加swagger的描述信息 */.description("歪鼻子个人博客 API 接口文档").version("1.0").termsOfServiceUrl("https://www.waibizi.com").version("1.0").contact(new Contact("歪鼻子", "https://www.waibizi.com", "1253658747@qq.com")).build();}
}

然后直接访问

项目Base路径+swagger-ui.html

因为我的路径配置了一个上下文，所以我的访问路径是

localhost:8888/blog/swagger-ui.html

为你接口加上中文注释

在Controller类加注解

@Api(value = "文章列表以及分类")
@RestController
public class SummaryListController {}

@Api注解说明

@Api：用在请求的类上，表示对类的说明

属性	解释
value	控制类的说明
tags	控制器的标签，设置了这个之后，value会被覆盖
produces	返回数据的Content type 例：“application/json, application/xml”，默认为空
consumes	接收数据的Content type 例：“application/json, application/xml”，默认为空
protocols	交互的协议例：http， https， ws， wss
authorizations	获取授权列表（安全声明），如果未设置，则返回一个空的授权值
hidden	配置为 true 将在文档中隐藏

接口方法上注解

 @ApiOperation(value = "获取分类",notes = "获取所有的分类信息，不用携带参数",produces = "application/json, application/xml",consumes="application/json, application/xml",response = Category.class,responseContainer = "List")@ApiResponses({@ApiResponse(code = 200 ,message = "响应正常"),@ApiResponse(code = 404 ,message = "资源不存在"),@ApiResponse(code = 500 ,message = "服务器内部错误")})@GetMapping("/category/list")public BlogResult GetCategoryList(){return BlogResult.success("查询成功",categoryService.categoryList());}

@ApiOperation注解说明

@ApiOperation：用在请求的方法上，说明方法的用途、作用

属性	解释
value	接口URL简要说明
notes	接口详细说明与备注
tags	如果设置这个值、 value的值会被覆盖
response	返回值的主体类
responseContainer	返回值的容器，只能是"List", “Set” or “Map”
responseReference	定对响应类型的引用。将覆盖任何指定的response（）类
httpMethod	“GET”、 “HEAD”、 “POST”、 “PUT”、 “DELETE”、 “OPTIONS” and “PATCH”
produces	返回数据的Content type 例：“application/json, application/xml”，默认为空
nickname	第三方工具唯一标识，默认为空
consumes	接收数据的Content type，例：“application/json, application/xml”，默认为空
protocols	交互的协议例：http， https， ws， wss
authorizations	获取授权列表（安全声明），如果未设置，则返回一个空的授权值
hidden	配置为 true 将在文档中隐藏
responseHeaders	响应头列表
code	响应的HTTP状态代码。默认 200
extensions	扩展属性列表数组

@ApiResponses注解说明

@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

属性	解释
code	响应的状态码
message	对应状态码的提示信息
response	抛出异常的类

@PostMapping("/article/summary/list/{categoryId}")
public BlogResult GetSummaryList( @ApiParam(name = "pageNum", value = "当前的页码", required = true) @RequestParam(value = "pageNum") int pageNum,@ApiParam(name = "pageSize", value = "一页显示数量", required = true) @RequestParam(value = "pageSize") int pageSize,@ApiParam(name = "categoryId", value = "分类的ID", required = true) @RequestParam(value = "categoryId") int categoryId){return BlogResult.success("查询成功",summaryService.summaryPage(pageNum,pageSize,categoryId));
}

@ApiParam注解说明

@ApiParam： 用在请求方法中，描述参数信息

属性	解释
name	参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
value	参数的简要说明
defaultValue	参数默认值
required	属性是否必填，默认为false [路径参数必须填]

实体类上注解（采用了lombok省略了setter与gettter）

@Getter
@Setter
@AllArgsConstructor
@ApiModel(description = "文章分类")
public class Category {@ApiModelProperty(value = "分类ID",name = "id")private int id;@ApiModelProperty(value = "类别名称",name = "categoryName")private String categoryName;
}

@ApiModel注解说明

@ApiModel：用于响应类上，表示一个返回响应数据的信息

这个就是一个description描述属性

@ApiModedProperty注解说明

@ApiModelProperty：用在属性上，描述响应类的属性

属性	解释
value	此属性的简要说明
name	允许覆盖属性名称