文章目录：
1.写在前面
2.步骤详解
2.1 pom文件中添加Swagger依赖
2.2 在application.properties核心配置文件中配置Swagger
2.3 编写需要生成API文档的控制层代码
2.4 编写Swagger的配置类
2.5 访问测试
1.写在前面
说到Swagger（丝袜哥），首先了解一下OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。（/OAI/OpenAPI-Specification）；
Swagger是目前最受欢迎的OpenAPI规范（OAS）开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发；
wagger官网：https://swagger.io/ 是一个开源项目，也就是提供jar包)；
Swagger2 版本：1.x，2.x，现在都用2.x；
Spring Boot也集成了Swagger，可以很方便地在springboot中使用Swagger生成api接口文档；
Swagger的作用：
随项目自动生成强大RESTful API文档，减少开发人员工作量；（不需要自己写api接口文档了），使用swagger，只需要在代码中添加一些注解即可生成API接口文档，便于同步更新API文档的说明，当然也有人诟病说这种方式与代码耦合在一起，智者见智仁者见仁；
另外生成的api文档页面带有测试功能，可以用来调试每个RESTful API接口；
2.步骤详解
2.1 pom文件中添加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>
2.2 在application.properties核心配置文件中配置Swagger
这是一个自定义配置，需要在配置类中使用@Value注解读取。只有一行代码，true表示开启Swagger；false表示关闭Swagger。
#开启或关闭Swaggerswagger.enable=true
2.3 编写需要生成API文档的控制层代码
在这个controller中，会用到大量的Swagger中的常用核心注解。
详细注解可参考官方：/swagger-api/swagger-core/wiki/Annotations
Swagger常用注解：
@Api：用在类上，说明该类的作用；
@ApiOperation：用在方法上，说明方法的作用；
@ApiImplicitParams：用在方法上包含一组参数说明；
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面:
paramType：参数放在哪个地方；
header-->请求参数的获取：@RequestHeader；
query-->请求参数的获取：@RequestParam；
path-->请求参数的获取：@PathVariable （用于restful接口）；
body（不常用）；
form（不常用）；
name： 参数名；
dataType：参数类型；
required：参数是否必须传；
value：参数的意思；
defaultValue：参数的默认值；
@ApiResponses：用于表示一组响应；
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息；
code：数字，例如400；
message：信息，例如 "请求参数不合法"；
response：抛出异常的类；
@ApiIgnore：使用该注解忽略这个API，在页面上不显示；
@ApiModel：描述一个Model的信息；
@ApiModelProperty：描述一个model的属性；
swagger安全性问题: 正式上线的时候，建议关闭swagger；
package com.szh.springboot.controller;import com.szh.springboot.model.User;import io.swagger.annotations.*;import org.springframework.stereotype.Controller;import org.springframework.web.bind.annotation.*;/****/@Api(tags = "SpringBoot集成Swagger2测试")@Controllerpublic class SwaggerController {@ApiOperation(value = "获取用户信息",notes = "根据id获取用户详细信息")@ApiImplicitParams({@ApiImplicitParam(paramType = "path",name = "id",value = "用户ID",dataType = "Integer"),@ApiImplicitParam(paramType = "path",name = "name",value = "用户姓名",dataType = "String"),})@ApiResponses({@ApiResponse(code = 200,message = "请求成功"),@ApiResponse(code = 400,message = "缺少必要的请求参数"),@ApiResponse(code = 401,message = "请求路径没有响应的权限"),@ApiResponse(code = 403,message = "请求路径被隐藏不能访问"),@ApiResponse(code = 404,message = "请求路径没有或页面跳转路径错误"),@ApiResponse(code = 405,message = "请求方法不支持"),})@RequestMapping(value = "/swagger/queryUser/{id}/{name}",method = RequestMethod.GET)public @ResponseBody User getUserInfo(@PathVariable("id") Integer id,@PathVariable("name") String name) {User user=new User();user.setId(id);user.setName(name);user.setPhone("18500000000");user.setEmail("szh@");return user;}@ApiOperation(value = "添加用户信息",notes = "将用户信息添加之后保存到数据库")@ApiImplicitParams({@ApiImplicitParam(paramType = "body",name = "users",value = "用户对象",dataTypeClass = User.class)})@ApiResponses({@ApiResponse(code = 200,message = "请求成功"),@ApiResponse(code = 400,message = "缺少必要的请求参数"),@ApiResponse(code = 401,message = "请求路径没有响应的权限"),@ApiResponse(code = 403,message = "请求路径被隐藏不能访问"),@ApiResponse(code = 404,message = "请求路径没有或页面跳转路径错误"),@ApiResponse(code = 405,message = "请求方法不支持"),})@RequestMapping(value = "/swagger/addUser",method = RequestMethod.POST)public @ResponseBody User addUser(@RequestBody User users) {return users;}@ApiOperation(value = "修改用户信息",notes = "将用户信息修改之后保存到数据库")@ApiImplicitParams({@ApiImplicitParam(paramType = "body",name = "users",value = "用户对象",dataTypeClass = User.class)})@ApiResponses({@ApiResponse(code = 200,message = "请求成功"),@ApiResponse(code = 400,message = "缺少必要的请求参数"),@ApiResponse(code = 401,message = "请求路径没有响应的权限"),@ApiResponse(code = 403,message = "请求路径被隐藏不能访问"),@ApiResponse(code = 404,message = "请求路径没有或页面跳转路径错误"),@ApiResponse(code = 405,message = "请求方法不支持"),})@RequestMapping(value = "/swagger/updateUser",method = RequestMethod.PUT)public @ResponseBody User updateUser(@RequestBody User users) {return users;}@ApiOperation(value = "删除用户信息",notes = "将用户信息从数据中删除")@ApiImplicitParams({@ApiImplicitParam(paramType = "query",name = "id",value = "用户ID",dataType = "Integer")})@ApiResponses({@ApiResponse(code = 200,message = "请求成功"),@ApiResponse(code = 400,message = "缺少必要的请求参数"),@ApiResponse(code = 401,message = "请求路径没有响应的权限"),@ApiResponse(code = 403,message = "请求路径被隐藏不能访问"),@ApiResponse(code = 404,message = "请求路径没有或页面跳转路径错误"),@ApiResponse(code = 405,message = "请求方法不支持"),})@RequestMapping(value = "/swagger/deleteUser",method = RequestMethod.DELETE)public @ResponseBody Object deleteUser(@RequestParam("id") Integer id) {return "成功删除了id为 " + id + " 的用户";}}
2.4 编写Swagger的配置类
在这个类中，使用@Value注解来读取核心配置文件中的自定义配置信息（开启或关闭Swagger的那个）
package com.szh.springboot.config;import io.swagger.annotations.ApiOperation;import org.springframework.beans.factory.annotation.Value;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;/****/@EnableSwagger2 //开启对Swagger2的支持@Configuration //声明当前类是一个配置类public class SwaggerConfig {@Value("${swagger.enable}")private Boolean swaggerEnable;//在Spring容器中配置一个Bean对象@Beanpublic Docket docket() {//链式编程（构建器模式），基本是固定return new Docket(DocumentationType.SWAGGER_2).enable(swaggerEnable).apiInfo(apiInfo()).select()//扫描带有ApiOperation注解的所有方法，为它们生成API接口文档.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any()).build();}//创建api的基本信息，自定义即可private ApiInfo apiInfo() {//链式编程（构建器模式），基本是固定return new ApiInfoBuilder().title("用户信息中心接口文档").description("SpringBoot集成Swagger2构建RESTful APIs").termsOfServiceUrl("/weixin_43823808").contact(new Contact("张起灵","/weixin_43823808","张起灵@")).version("1.0.0").build();}}
2.5 访问测试
上面几步都完成后，输入这个url访问：http://localhost:8080/swagger-ui.html 得到API文档；（如果项目有上下文根，要在端口号的后面加上项目上下文根）
将核心配置文件中的swagger.enable设置为true，即可看到如下结果
将其设置为false，就不能访问生成API文档了。
