SpringBoot从零入门6_Swagger2生成生产环-创新互联

1 前言

在如今前后端分离开发的模式下，前端调用后端提供的API去实现数据的展示或者相关的数据操作，保证及时更新和完整的REST API文档将会大大地提高两边的工作效率，减少不必要的沟通成本。本文采用的Swagger2就是一个当前流行的通过少量的注解就可以生成漂亮的API文档工具，且在生成的在线文档中提供类似POSTMAN直接调试能力，不仅仅是静态的文档。接下来将会利用这个工具与Spring Boot项目结合，最终生成我们上一篇文章中所涉及到的REST API文档。

为横峰等地区用户提供了全套网页设计制作服务，及横峰网站建设行业解决方案。主营业务为成都做网站、网站建设、横峰网站设计，以传统方式定制建设网站，并提供域名空间备案等一条龙服务，秉承以专业、用心的态度为用户提供真诚的服务。我们深信只要达到每一位用户的要求，就会得到认可，从而选择与我们长期合作。这样，我们也可以走得更远！

这一篇文章基本将Swagger2在生产环境中可能会用到的配置都有涉及，慢慢看吧，看了这一篇因该是够了。

2 Swagger2简介

Swagger是与用于实现 OpenAPI 文档广泛使用的工具，Swagger工具集包括开源工具，免费工具和商业工具的组合，可在API生命周期的不同阶段使用。

Swagger Editor(开源)：使用Swagger编辑器，可以在浏览器内的YAML文档中编辑OpenAPI规范并支持实时预览文档，可以参考官方的Demo https://editor.swagger.io/
Swagger UI(开源)：让Swagger产生的文档更漂亮，而且支持API交互操作，在生成文档后，直接在浏览器中浏览，并可以实现类似curl命令或者postman访问我们的API，并返回相关数据。
Swagger Codegen(开源): 是一个代码生成器，可以通过Swagger API定义生成不同语言版本的服务端和客户端工程代码。
Swagger Core(开源)：用于生成Swagger API规范的示例和服务器集成，可轻松访问REST API，结合Swagger UI，让生成的文档更漂亮。
Swagger Parser(开源)： Java开发，解析OpenAPI定义的独立库
Swagger Inspector(免费)：API在线测试工具，验证API并从现有API生成OpenAPI定义功能 https://goo.gl/fZYHWz
SwaggerHub(免费和商用版)：API设计和文档化，为使用OpenAPI的团队打造。

3 开始使用

3.1 构建Restful WEB服务

参考《Spring Boot从零入门5_五脏俱全的RESTful Web Service构建》。构建好后有如下REST API:

# 获取所有用户信息GET http://localhost:8080/api/v1/users# 新增一个用户，参数通过body传递POST http://localhost:8080/api/v1/users# 更新一个用户信息PUT http://localhost:8080/api/v1/users/{id}# 删除指定用户DELETE http://localhost:8080/api/v1/users/{id}

3.2 集成Swagger2

构建好RESTful WEB服务后，接下来我们集成Swagger，然后对上节中的REST API自动生成接口文档。

3.2.1 pom.xml添加依赖

集成Swagger2，需要在pom.xml中添加依赖源：


	
	    io.springfox
	    springfox-swagger2
	    
	    
	    2.9.2

3.2.2 Swagger 配置及初始化

springfox有一个专用对象Docket，可以灵活的配置Swagger的各种属性，首先我们简单的创建一个Swagger配置类Swagger2Config.java：

@Configuration@EnableSwagger2
public class Swagger2Config {
    @Bean("UsersApis")
    public Docket usersApis() {        return new Docket(DocumentationType.SWAGGER_2)                .select()                .apis(RequestHandlerSelectors.any())                .paths(PathSelectors.any())                .build();
    }
}

这里的@Configuration注解用于定义配置类，被注解的类内部包含有一个或多个被@Bean注解的方法，这些方法将会被AnnotationConfigApplicationContext类进行扫描，并用于构建Bean定义，初始化对象。@ComponentScan会自动获取所有的Spring Components，包括@Configuration类。另外这里的“用户管理模块”API生成配置很简单，对所有路径上API都去生成文档。

3.2.3 启动服务并验证

当完成Swagger2的配置类时，启动WEB服务，通过http://localhost:8080/v2/api-docs就可以访问生成文档内容，但是浏览器返回的是JSON内容，基本上很难给需要用到相关API的开发人员进行参考。这个时候就需要用到Swagger2 UI了。

3.3 集成Swagger2 UI

pom.xml添加依赖，然后重启WEB服务就可以了，再次访问http://localhost:8080/swagger-ui.html，这时候看到的就是WEB文档了。


    io.springfox
    springfox-swagger-ui
    2.9.2

Spring Boot从零入门6_Swagger2生成生产环

从swagger-ui页面看到的内容有一部无关的内容，或者是如何明显表现跟项目相关的内容呢？下面章节详细讲解Swagger的各种配置，能够应用到实际生产环境中去。

4 Swagger2 深度配置

4.1 深度配置目标

首先，如果要将我们最后生成的API文档给生产环境的开发人员查阅，那么友好的展示信息和归类是很有必要的，我们接下来实现如下目标：

文档的各种信息说明
- 文档标题
- 文档描述
- 文档版本号
- Logo
- 文档责任人
- 文档许可证信息
- 文档服务条款
API分组
- 组描述
- 各API描述
附加部分(非API)
定制化文档页面风格

为了更好地展示API分组功能，这里另外加了一组REST API (代码层面上只需要将User相关的代码全部复制一份，将User关键字全部改为Product就可以了，包括大小写)：

# 获取所有产品信息GET http://localhost:8080/api/v1/products# 新增一个产品，参数通过body传递POST http://localhost:8080/api/v1/products# 更新一个产品信息PUT http://localhost:8080/api/v1/products/{id}# 删除指定产品DELETE http://localhost:8080/api/v1/products/{id}

4.2 文档信息配置

@Configuration@EnableSwagger2public class Swagger2Config {    @Bean("UsersApis")    public Docket usersApis() {        return new Docket(DocumentationType.SWAGGER_2)        		// select()返回的是ApiSelectorBuilder对象，而非Docket对象
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())                 
                // build()返回的是Docket对象
                .build()                // 测试API时的主机URL
                .host("https://xiaobaiai.net")    
                // API前缀
                .pathProvider(new RelativePathProvider(null) {                    @Override
                    public String getApplicationBasePath() {                        return "/prefix";
                    }
                })
                .apiInfo(apiInfo());
    }    
    public ApiInfo apiInfo() {    	// API负责人的联系信息
    	final Contact contact = new Contact(    			"Ethan", "https://xiaobaiai.net", "ycm_hy@163.com");        return new ApiInfoBuilder()        	// API文档标题
            .title("X系统平台接口文档")            // API文档描述
            .description("用户/产品相关API, 更多请关注公众号: 小白AI 或微信小程序：小白AI博客")            // 服务条款URL
            .termsOfServiceUrl("https://github.com/yicm")            // API文档版本
            .version("1.0")            // API负责人的联系信息
            .contact(contact)            // API的许可证Url
            .licenseUrl("http://license.coscl.org.cn/MulanPSL")
            .license("MulanPSL")
            .build();
    }
}

通过添加文档信息编译对象ApiInfoBuilder可以配置API文档的各种信息，包括标题、描述、服务条款、版本、责任人、许可证等。最后在Docket中添加信息配置对象即可生效。

4.3 API分组配置、API精细配置

4.3.1 API分组展示

上面的文档信息配置中默认是没有对API分组的，即所有的API都展示在了一个页面，没有隔离，如果需要分组，那我们需要对不同API组分配Bean，目前示例可以分为用户API组和产品API组，然后通过apis() 和 paths()进行API过滤。

为了不显示某个包下面API或某个URL路径下API， Docket提供了 apis() 和 paths() 两个方法来帮助我们在不同级别上过滤接口（上面示例我们默认对这两个设置是不做任何过滤，扫描所有API）：

apis()：这种方式可以通过指定包名的方式，让 Swagger2 只去某些包下面扫描
paths()：这种方式可以通过筛选 API 的 URL 来进行过滤

apis和paths中的Predicates除了any、ant、none，还支持regex正则表达式。

如：

PathSelectors.regex("/api/v2/users.*")

下面就是分组示例代码，实现分组，很简单，就是在Docket中配置组名就好了：

@Configuration@EnableSwagger2public class Swagger2Config {    @Bean
    public Docket usersApis() {        return new Docket(DocumentationType.SWAGGER_2)
        		.groupName("用户管理接口")        		// select()返回的是ApiSelectorBuilder对象，而非Docket对象
                .select()
                
                .apis(RequestHandlerSelectors.basePackage("com.xiaobaiai.user"))
                .paths(Predicates.or(                        // 两个**，可以匹配底下所有URL
                        // 一个*，只能匹配一级URL分段
                        PathSelectors.ant("/api/v1/users/**"),
                        PathSelectors.ant("/api/v1/users/*")))              
                // build()返回的是Docket对象
                .build()                // 测试API时的主机URL
                .host("https://xiaobaiai.net")    
                // API前缀，最终所有API的基础地址就是host+prefix: https://xiaobaiai.net/prefix
                .pathProvider(new RelativePathProvider(null) {                    @Override
                    public String getApplicationBasePath() {                        return "/prefix";
                    }
                })
                .apiInfo(apiInfo());
    }    
    @Bean
    public Docket productsApis() {        return new Docket(DocumentationType.SWAGGER_2)
        		.groupName("产品管理接口")        		// select()返回的是ApiSelectorBuilder对象，而非Docket对象
                .select()
                
                .apis(RequestHandlerSelectors.basePackage("com.xiaobaiai.product"))
                .paths(Predicates.or(                        // 两个**，可以匹配底下所有URL
                        // 一个*，只能匹配一级URL分段
                        PathSelectors.ant("/api/v1/products/**"),
                        PathSelectors.ant("/api/v1/products/*")))              
                // build()返回的是Docket对象
                .build()                // 测试API时的主机URL
                .host("https://xiaobaiai.net")    
                // API前缀
                .pathProvider(new RelativePathProvider(null) {                    @Override
                    public String getApplicationBasePath() {                        return "/prefix";
                    }
                })
                .apiInfo(apiInfo());
    }    
    public ApiInfo apiInfo() {    	// API负责人的联系信息
    	final Contact contact = new Contact(    			"Ethan", "https://xiaobaiai.net", "ycm_hy@163.com");        return new ApiInfoBuilder()        	// API文档标题
            .title("X系统平台接口文档")            // API文档描述
            .description("用户/产品相关API, 更多请关注公众号: 小白AI 或微信小程序：小白AI博客")            // 服务条款URL
            .termsOfServiceUrl("https://github.com/yicm")            // API文档版本
            .version("1.0")            // API负责人的联系信息
            .contact(contact)            // API的许可证Url
            .licenseUrl("http://license.coscl.org.cn/MulanPSL")
            .license("MulanPSL")
            .build();
    }
}

分组配置完成后，重新启动，打开浏览器就可以看到效果了：

Spring Boot从零入门6_Swagger2生成生产环