Swagger使用简介
前言
Swagger，可用于生成、描述、调用和可视化 RESTful 风格接口的API，是一套规范和完整的开发框架，并且能对接口进行单独测试。
无论对于后端开发，还是前端开发以及测试同事，Swagger 都可以基本满足使用需求。
在 SpringBoot 中集成 Swagger，后端同事写完接口就可以自动生成API文档，可以给到前端同事看，测试同事可以直接测试该接口。
在本篇中，跟大家分享如下内容：
- 在 SpringBoot 中项目如何集成 Swagger？
- 如何使用 Swagger，如何在不同的环境中开启和关闭 Swagger？
- 如何将同类的接口使用 Swagger 注解进行聚合？
集成 Swagger
在 MavenEwpository搜索 Springfox，可以找到 Swagger2 和 Swagger UI，如图所示。
截止到目前， Swagger2 和 Swagger UI 最新版本是 2.9.2 版本。
修改工程的pom文件，增加 Swagger2 和 Swagger UI 的依赖，如下：
1
2
3
4
5
6
7
8
9
10
11
|
<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>
|
因为我的项目已经集成了 starter-web，如下 pom 文件中的 dependency：
1
2
3
4
| <dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
|
这样默认会集成 com.fasterxml.jackson.core: 相关的库，不需要额外再去集成 jackson-databind 了，如下图所示：
否则你需要单独增加 jackson-databind 的依赖，同样的道理你可以在 MavenEwpository 搜索 jackson-databind 选择合适的版本即可。
否则你需要单独增加 jackson-databind 的依赖，同样的道理你可以在 MavenEwpository 搜索 jackson-databind 选择合适的版本即可。
1
2
3
4
5
| <dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.9.8</version>
</dependency>
|
工程已经集成了 Swagger，接下来我们看看如何使用。
使用 Swagger
创建Swagger配置
新建一个配置类 MSSwaggerConfig，该文件名称和位置你可以放到你的工程的任意目录，根据自己的项目目录来放置即可。
MSSwaggerConfig 示例代码如下：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
| @Configuration
@EnableSwagger2
public class MSSwaggerConfig {
@Bean
public Docket msblogDocket() {
Docket docket = new Docket(DocumentationType.SWAGGER_2);
String pkgName = "com.veryitman.springboot.controller";
return docket.apiInfo(msblogAPIInfo()).select()
.apis(RequestHandlerSelectors.basePackage(pkgName))
.paths(PathSelectors.any())
.build();
}
private ApiInfo msblogAPIInfo() {
ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
String apiTitle = "MSBlog Server API";
String apiDes = "API for MSBlog";
String apiVersion = "1.0.0";
String homePage = "http://veryitman.com";
String emailUrl = "veryitman@126.com";
Contact contact = new Contact("itman", homePage, emailUrl);
return apiInfoBuilder.title(apiTitle).description(apiDes)
.version(apiVersion)
.contact(contact)
.license("Apache 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.build();
}
}
|
记得添加 @Configuration、 @EnableSwagger2 这两个注解。
对于 apis(RequestHandlerSelectors.basePackage(pkgName)) 目的是只扫描指定包名下面 Controller 的 Swagger 注解，这样就不会去扫描其他包下面的类了。
对于这个配置类，主要是用来生成一些摘要信息，如图：
注解 Controller
在 微服务-简单的用户名注册和登录 给大家分享了如何写注册和登录的API，今天还是拿注册的例子来进行 Swagger 的演示。
下面代码是用户注册的示例代码。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| @RestController
@RequestMapping(value = "signup")
public class MSSignupController {
@CrossOrigin(origins = {"*"})
@PostMapping(value = "/name")
@ApiOperation(value = "用户注册", httpMethod = "POST", notes = "用户名和密码注册")
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "注册的用户名", required = true),
@ApiImplicitParam(name = "userpwd", value = "注册的密码", required = true)
})
public MSResponse signup(@RequestParam(value = "username") String userName, @RequestParam(value = "userpwd") String userPwd) {
}
}
|
可以看到如下的注解：
1
2
3
4
5
| @ApiOperation(value = "用户注册", httpMethod = "POST", notes = "用户名和密码注册")
@ApiImplicitParams({
@ApiImplicitParam(name = "username", value = "注册的用户名", required = true),
@ApiImplicitParam(name = "userpwd", value = "注册的密码", required = true)
})
|
这些注解就是 Swagger 的注解，@ApiOperation 说明了该接口的用途，@ApiImplicitParams 中有两个 @ApiImplicitParam 用来对接口的参数进行说明。
如果接口只有一个参数，可以直接使用 @ApiImplicitParam 注解即可。
在线文档
配置完成之后，可以启动 SpringBoot 项目，在浏览器中打开下面地址，就可以看到生成的在线文档了。
http://localhost:8080/swagger-ui.html#/
点击对应的 Controller 就可以看到对应接口的详细说明了，并且还可以对接口进行测试。
分环境开启 Swagger
在实际项目中，我们一般只会在开发和测试环境使能 Swagger，在沙盒和生成环境会关闭 Swagger，那如何控制呢？
在工程的 Resources 目录下面，新建几个跟环境相关的 properties 文件。
这些文件的命令要满足 application-{profile}.properties 的格式，其中 {profile} 你可以自定义名字，如下我自定义了4个环境，分别是开发、生产、沙盒和测试环境。
我们知道，在 application-{profile}.properties 中配置的选项与在 application.properties 中配置的选项如果名称相同，优先会使用 application-{profile}.properties 中配置。
在 application.properties 中配置如下：
1
2
3
4
|
spring.profiles.active=dev
swagger.enable=false
|
对应的在 application-dev.properties 和 application-test.properties 中开启 swagger，如下：
选项配置完成后，我们在代码中使用该选项，修改 MSSwaggerConfig 如下(只列出了修改部分的关键代码)：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| @Configuration
@EnableSwagger2
public class MSSwaggerConfig {
@Value("${swagger.enable}")
private boolean enableSwagger;
@Bean
public Docket msblogDocket() {
Docket docket =
new Docket(DocumentationType.SWAGGER_2).enable(enableSwagger);
String pkgName = "com.veryitman.springboot.controller";
return docket.apiInfo(msblogAPIInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(pkgName))
.paths(PathSelectors.any())
.build();
}
|
在下面的代码中读取配置
1
2
| @Value("${swagger.enable}")
private boolean enableSwagger;
|
然后调用 Docket 的 enable(enableSwagger) 方法来决定是否开启 Swagger，如果配置不开启，效果图如下：
还有其他方式来控制在不同环境下配置 Swagger 是否开启，比如可以结合注解 @Profile 通过不同的 profile 给 Swagger 的依赖设置不同的 scope，还可以使用注解 @ConditionalOnProperty(name = “swagger.enable”, havingValue = “true”)，大家自行选择适合自己项目的方案即可，目的都是一样。
聚合接口
在上面实例中，我们可以看到登录和注册都属于用户模块，使用注解 @API 可以聚合显示这些接口。
在登录和注册的 Controller 中可以添加下面注解，从而来聚合显示接口。
1
| @Api(value="xxx", tags="用户模块")
|
注册 Controller 添加注解，如下：
1
2
3
4
| @Api(value="signup", tags="用户模块")
@RestController
@RequestMapping(value = "signup")
public class MSSignupController {
|
登录 Controller 添加注解，如下：
1
2
3
4
5
| @Api(value="signin", tags="用户模块")
@RestController
@RequestMapping(value = "signin")
public class MSSigninController {
}
|
显示效果如下：
参考资料