一、为什么使用Swagger2
当下很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发模式下，维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式，下面我们就来了解一下它的优点：
1、代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
2、跨语言性，支持 40 多种语言。
3、Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。
4、还可以将文档规范导入相关的工具（例如 Postman、SoapUI）, 这些工具将会为我们自动地创建自动化测试。
二、配置使用Swagger2
1、在pom.xml加入swagger2相关依赖
1 <!--swagger2的依赖--> 2 <dependency> 3 <groupId>io.springfox</groupId> 4 <artifactId>springfox-swagger2</artifactId> 5 <version>2.9.2</version> 6 </dependency> 7 <dependency> 8 <groupId>io.springfox</groupId> 9 <artifactId>springfox-swagger-ui</artifactId> 10 <version>2.9.2</version> 11 </dependency>
2、新建Swagger2Config配置类
1 import io.swagger.annotations.Api;
2 import org.springframework.context.annotation.Bean;
3 import org.springframework.context.annotation.Configuration;
4 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
5 import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
6 import springfox.documentation.builders.ApiInfoBuilder;
7 import springfox.documentation.builders.PathSelectors;
8 import springfox.documentation.builders.RequestHandlerSelectors;
9 import springfox.documentation.service.*;
10 import springfox.documentation.spi.DocumentationType;
11 import springfox.documentation.spi.service.contexts.SecurityContext;
12 import springfox.documentation.spring.web.plugins.Docket;
13 import springfox.documentation.swagger2.annotations.EnableSwagger2;
14
15 import java.util.ArrayList;
16 import java.util.List;
17
18 /**
19 * @author yunqing
20 * @date 2019/12/17 10:23
21 */
22 @Configuration
23 @EnableSwagger2
24 public class Swagger2Config extends WebMvcConfigurationSupport {
25 @Bean
26 public Docket createRestApi(){
27 return new Docket(DocumentationType.SWAGGER_2)
28 .apiInfo(apiInfo())
29 .select()
30 //为当前包下controller生成API文档
31 // .apis(RequestHandlerSelectors.basePackage("com.troila"))
32 //为有@Api注解的Controller生成API文档
33 // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
34 //为有@ApiOperation注解的方法生成API文档
35 // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
36 //为任何接口生成API文档
37 .apis(RequestHandlerSelectors.any())
38 .paths(PathSelectors.any())
39 .build();
40 //添加登录认证
41 /*.securitySchemes(securitySchemes())
42 .securityContexts(securityContexts());*/
43 }
44
45 private ApiInfo apiInfo() {
46 Contact contact = new Contact("yunqing", "", "yunqing****@gmail.com");
47 return new ApiInfoBuilder()
48 .title("SwaggerUI演示")
49 .description("接口文档，描述词省略200字")
50 .contact(contact)
51 .version("1.0")
52 .build();
53 }
54
55 /**
56 * 配置swagger2的静态资源路径
57 * @param registry
58 */
59 @Override
60 protected void addResourceHandlers(ResourceHandlerRegistry registry) {
61 // 解决静态资源无法访问
62 registry.addResourceHandler("/**")
63 .addResourceLocations("classpath:/static/");
64 // 解决swagger无法访问
65 registry.addResourceHandler("/swagger-ui.html")
66 .addResourceLocations("classpath:/META-INF/resources/");
67 // 解决swagger的js文件无法访问
68 registry.addResourceHandler("/webjars/**")
69 .addResourceLocations("classpath:/META-INF/resources/webjars/");
70 }
71
72
73 /**
74 * 给API文档接口添加安全认证
75 */
76 /*private List<ApiKey> securitySchemes() {
77 List<ApiKey> apiKeys = new ArrayList<>();
78 apiKeys.add(new ApiKey("Authorization", "Authorization", "header"));
79 return apiKeys;
80 }
81
82 private List<SecurityContext> securityContexts() {
83 List<SecurityContext> securityContexts = new ArrayList<>();
84 securityContexts.add(SecurityContext.builder()
85 .securityReferences(defaultAuth())
86 .forPaths(PathSelectors.regex("^(?!auth).*$")).build());
87 return securityContexts;
88 }
89
90 private List<SecurityReference> defaultAuth() {
91 AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
92 AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
93 authorizationScopes[0] = authorizationScope;
94 List<SecurityReference> securityReferences = new ArrayList<>();
95 securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
96 return securityReferences;
97 }*/
98 }
3、在shiro配置类中放行swagger2相关资源
1 //swagger2免拦截
2 filterChainDefinitionMap.put("/swagger-ui.html**", "anon");
3 filterChainDefinitionMap.put("/v2/api-docs", "anon");
4 filterChainDefinitionMap.put("/swagger-resources/**", "anon");
5 filterChainDefinitionMap.put("/webjars/**", "anon");
4、配置为哪部分接口生成API文档
主要是在Swagger2Config配置类中进行createRestApi()方法中进行配置，下面提供四种配置：
①为任何接口生成API文档，这种方式不必在接口方法上加任何注解，方便的同时也会因为没有添加任何注解所以生成的API文档也没有注释，可读性不高。
1 @Bean
2 public Docket createRestApi(){
3 return new Docket(DocumentationType.SWAGGER_2)
4 .apiInfo(apiInfo())
5 .select()
6 //为任何接口生成API文档
7 .apis(RequestHandlerSelectors.any())
8 .paths(PathSelectors.any())
9 .build();
10 }
②为当前配置的包下controller生成API文档
.apis(RequestHandlerSelectors.basePackage("com.troila"))
③为有@Api注解的Controller生成API文档
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
④为有@ApiOperation注解的方法生成API文档
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
三、Swagger2注解详解
1、@Api ：请求类的说明
@Api：放在请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
tags="说明该类的作用"
value="该参数没什么意义，所以不需要配置"
举例：
1 @Api(tags = "账户相关模块")
2 @RestController
3 @RequestMapping("/api/account")
4 public class AccountController {
5 //TODO
6 }
2、@ApiOperation：方法的说明
@ApiOperation："用在请求的方法上，说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"
举例：
1 @ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
2 @PostMapping("/changepass")
3 public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
4 @RequestBody @Valid PasswordModel passwordModel) {
5 //TODO
6 }
3、@ApiImplicitParams、@ApiImplicitParam：方法参数的说明
@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（请求体）--> @RequestBody User user
· form（普通表单提交）
dataType：参数类型，默认String，其它值dataType="int"
defaultValue：参数的默认值
举例：
1 @ApiOperation(value="用户登录",notes="随边说点啥")
2 @ApiImplicitParams({
3 @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
4 @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
5 @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
6 })
7 @PostMapping("/login")
8 public AjaxResult login(@RequestParam String mobile, @RequestParam String password,
9 @RequestParam Integer age){
10 //TODO
11 return AjaxResult.OK();
12 }
单个参数举例
@ApiOperation("根据部门Id删除")
@ApiImplicitParam(name="depId",value="部门id",required=true,paramType="query")
@GetMapping("/delete")
public AjaxResult delete(String depId) {
//TODO
}
4、@ApiResponses、@ApiResponse：方法返回值的说明
@ApiResponses：方法返回对象的说明
@ApiResponse：每个参数的说明
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
举例：
1 @ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
2 @ApiResponses({
3 @ApiResponse(code = 400, message = "请求参数没填好"),
4 @ApiResponse(code = 404, message = "请求路径找不到")
5 })
6 @PostMapping("/changepass")
7 public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
8 @RequestBody @Valid PasswordModel passwordModel) {
9 //TODO
10 }
5、@ApiModel：用于JavaBean上面，表示一个JavaBean
@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息
（这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 ）
6. @ApiModelProperty：用在JavaBean的属性上面，说明属性的含义
@ApiModel和 @ApiModelProperty举例：
1 @ApiModel("修改密码所需参数封装类")
2 public class PasswordModel
3 {
4 @ApiModelProperty("账户Id")
5 private String accountId;
6 //TODO
7 }
总结：API文档浏览地址
配置好Swagger2并适当添加注解后，启动SpringBoot应用，
访问http://localhost:8080/swagger-ui.html 即可浏览API文档。
另外，我们需要为了API文档的可读性，适当的使用以上几种注解就可以。
四、把Swagger2的API接口导入Postman
1、访问http://localhost:8080/swagger-ui.html 文档的首页，复制下面这个地址
2.打开postman-->import-->import Form Link
