微服务: Swagger 实现在线文档自动化

---

原文 微服务: Swagger让你可以多抽一支烟，优快云同步发布。

转载请注明出处，谢谢！

---

简介

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

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

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

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

在本篇中，跟大家分享如下内容：

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

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

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

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

集成 Swagger

在 MavenEwpository 搜索 Springfox，可以找到 Swagger2 和 Swagger UI，如图所示。

截止到目前， Swagger2 和 Swagger UI 最新版本是 2.9.2 版本。

修改工程的pom文件，增加 Swagger2 和 Swagger UI 的依赖，如下：

<!--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：

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-starter-web</artifactId>
</dependency>

这样默认会集成 com.fasterxml.jackson.core: 相关的库，不需要额外再去集成 jackson-databind 了，如下图所示：

否则你需要单独增加 jackson-databind 的依赖，同样的道理你可以在 MavenEwpository 搜索 jackson-databind 选择合适的版本即可。

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.9.8</version>
</dependency>

工程已经集成了 Swagger，接下来我们看看如何使用。

使用 Swagger

1、创建Swagger配置

新建一个配置类 MSSwaggerConfig，该文件名称和位置你可以放到你的工程的任意目录，根据自己的项目目录来放置即可。

MSSwaggerConfig 示例代码如下：

@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 注解，这样就不会去扫描其他包下面的类了。

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

2、注解 Controller

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

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

@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) {
       // 省略
    }
}

可以看到如下的注解：

@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 项目，在浏览器中打开下面地址，就可以看到生成的在线文档了。

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 中配置如下：

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

对应的在 application-dev.properties 和 application-test.properties 中开启 swagger，如下：

# 启用 swagger
swagger.enable=true

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

@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();
    }

在下面的代码中读取配置

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

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

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

聚合接口

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

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

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

注册 Controller 添加注解，如下：

@Api(value="signup", tags="用户模块")
@RestController
@RequestMapping(value = "signup")
public class MSSignupController {
}

登录 Controller 添加注解，如下：

@Api(value="signin", tags="用户模块")
@RestController
@RequestMapping(value = "signin")
public class MSSigninController {
}

显示效果如下：

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