发布于 

微服务: Swagger让你可以多抽一支烟

简介

Swagger,可用于生成、描述、调用和可视化 RESTful 风格接口的API,是一套规范和完整的开发框架,并且能对接口进行单独测试。

另外, Swagger 在 Github 上面是开源的。

无论对于后端开发,还是前端开发以及测试同事,Swagger 都可以基本满足使用需求。

在 SpringBoot 中集成 Swagger,后端同事写完接口就可以自动生成API文档,可以给到前端同事看,测试同事可以直接测试该接口。

在本篇中,跟大家分享如下内容:

1、在 SpringBoot 中项目如何集成 Swagger?

2、如何使用 Swagger,如何在不同的环境中开启和关闭 Swagger?

3、如何将同类的接口使用 Swagger 注解进行聚合?

更多关于 SpringBoot 的文章,可以点击 微服务项目系列文章 了解,完整代码示例请前往 Github 查看。

集成 Swagger

MavenEwpository 搜索 Springfox,可以找到 Swagger2Swagger UI,如图所示。

1568529858131

截止到目前, Swagger2Swagger UI 最新版本是 2.9.2 版本。

修改工程的pom文件,增加 Swagger2Swagger UI 的依赖,如下:

1
2
3
4
5
6
7
8
9
10
11
<!--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>

因为我的项目已经集成了 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 了,如下图所示:

1568529858131

否则你需要单独增加 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

1、创建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
29
30
@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 注解,这样就不会去扫描其他包下面的类了。

对于这个配置类,主要是用来生成一些摘要信息,如图:

1568529858131

2、注解 Controller

微服务-简单的用户名注册和登录 给大家分享了如何写注册和登录的API,今天还是拿注册的例子来进行 Swagger 的演示。

下面代码是用户注册的示例代码。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@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 注解即可。

3、在线文档

配置完成之后,可以启动 SpringBoot 项目,在浏览器中打开下面地址,就可以看到生成的在线文档了。

1
http://localhost:8080/swagger-ui.html#/

1568529858131

点击对应的 Controller 就可以看到对应接口的详细说明了,并且还可以对接口进行测试。

分环境开启 Swagger

在实际项目中,我们一般只会在开发和测试环境使能 Swagger,在沙盒和生成环境会关闭 Swagger,那如何控制呢?

在工程的 Resources 目录下面,新建几个跟环境相关的 properties 文件。

这些文件的命令要满足 application-{profile}.properties 的格式,其中 {profile} 你可以自定义名字,如下我自定义了4个环境,分别是开发、生产、沙盒和测试环境。

1568529858131

我们知道,在 application-{profile}.properties 中配置的选项与在 application.properties 中配置的选项如果名称相同,优先会使用 application-{profile}.properties 中配置。

application.properties 中配置如下:

1
2
3
4
# 配置使用哪个环境
spring.profiles.active=dev
# 默认不启用 swagger
swagger.enable=false

对应的在 application-dev.propertiesapplication-test.properties 中开启 swagger,如下:

1
2
# 启用 swagger
swagger.enable=true

选项配置完成后,我们在代码中使用该选项,修改 MSSwaggerConfig 如下(只列出了修改部分的关键代码):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
@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()
// 只扫描指定包名下面的Controller中的Swagger注解
.apis(RequestHandlerSelectors.basePackage(pkgName))
.paths(PathSelectors.any())
.build();
}

在下面的代码中读取配置

1
2
@Value("${swagger.enable}")
private boolean enableSwagger;

然后调用 Docket 的 enable(enableSwagger) 方法来决定是否开启 Swagger,如果配置不开启,效果图如下:

1568529858131

还有其他方式来控制在不同环境下配置 Swagger 是否开启,比如可以结合注解 @Profile 通过不同的 profile 给 Swagger 的依赖设置不同的 scope,还可以使用注解 @ConditionalOnProperty(name = "swagger.enable", havingValue = "true"),大家自行选择适合自己项目的方案即可,目的都是一样。

聚合接口

在上面实例中,我们可以看到登录和注册都属于用户模块,使用注解 @API 可以聚合显示这些接口。

在登录和注册的 Controller 中可以添加下面注解,从而来聚合显示接口。

1
@Api(value="xxx", tags="用户模块")

注册 Controller 添加注解,如下:

1
2
3
4
5
@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 {
}

显示效果如下:

1568529858131


你眼睛看到的不一定是事实的全部~


本博客所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议,转载请注明出处。

veryitman