Spring Boot——集成Swagger2
问题描述
在团队开发中,一个好的 API 文档不但可以减少大量的沟通成本,还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节,并在程序员之间代代相传。
这种做法存在以下几个问题:
- API 接口众多,细节复杂,需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等,想要高质量的完成这份文档需要耗费大量的精力;
- 难以维护。随着需求的变更和项目的优化、推进,接口的细节在不断地演变,接口描述文档也需要同步修订,可是文档和代码处于两个不同的媒介,除非有严格的管理机制,否则很容易出现文档、接口不一致的情况
- 接口测试不方便,一般只能借助第三方工具(如:Postman)来测试。
基本概念
Swagger2 是一个开源软件框架,从根本上解决上述问题。它作为一个规范和完整的框架,可以用于设计、生成、描述、调用和可视化 RESTful 风格的 Web 服务,使开发人员将大部分精力集中到业务中,而不是繁杂琐碎的文档中:
- 接口文档在线自动生成,文档随接口变动实时更新,节省维护成本。
- 支持在线接口测试,不依赖第三方工具。
- 将代码和文档融为一体。
Maven
<dependencies>
...
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
</dependencies>
解决方案
配置类
Swagger2Configuration.java
package com.zstu.metrocity.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @Author ShenTuZhiGang
* @Version 1.0.0
* @Date 2020-04-13 19:57
* Swagger2 配置类
*/
@Configuration
@EnableSwagger2
public class CustomSwagger2Config {
@Bean
Docket docket(){
return new Docket(DocumentationType.SPRING_WEB)
.select()
//配置需要扫描的controller位置
.apis(RequestHandlerSelectors.basePackage("com.zstu.controller"))
//配置路径
.paths(PathSelectors.any())
//构建
.build()
//文档信息
.apiInfo(new ApiInfoBuilder()
//描述
.description("MetroCity RESTful API 文档")
//联系人信息
.contact(new Contact("申屠志刚",//名字
"https://shentuzhigang.blog.csdn.net/",//网址
"aaa@qq.com"))//邮箱
//版本
.version("V1.0")
//标题
.title("MetroCity RESTful API 文档")
//License
.license("Apache 2.0")
//License 网址
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
.build());
}
}
Swagger2Configuration.java 配置类的内容不多,配置完成后也很少变化,简单了解即可。
如上代码所示,通过 @Configuration
注解,让 Spring 加载该配置类。再通过 @EnableSwagger2
注解来启用Swagger2。成员方法 createRestApi
函数创建 Docket
的Bean之后,apiInfo()
用来创建该 Api 的基本信息(这些基本信息会展现在文档页面中)。select()
函数返回一个 ApiSelectorBuilder
实例用来控制哪些接口暴露给 Swagger 来展现,本例采用指定扫描的包路径来定义,Swagger 会扫描该包下所有 Controller 定义的 API,并产生文档内容(除了被 @ApiIgnore
指定的请求)。
API 接口编写
在完成了上述配置后,其实已经可以产生文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容。
@Api(description = "生产者进程API接口")
@RestController
@RequestMapping("/producer")
public class ActiveMQProducer {
private static final Logger logger = LoggerFactory.getLogger(ActiveMQConsumer.class);
@Value(value = "${mq.active.count-queue-name}")
private String COUNT_QUEUE_NAME;
@Value(value = "${mq.active.query-queue-name}")
private String QUERY_QUEUE_NAME;
@Autowired
private ActiveMQManager mqManager;
@ApiOperation(value="发送解析文本", notes="发送解析文本", produces="application/json")
@RequestMapping(value="/sendText", produces={ MediaType.APPLICATION_JSON_UTF8_VALUE }, consumes={ MediaType.APPLICATION_JSON_UTF8_VALUE }, method=RequestMethod.POST)
public String sendText(@RequestBody String text) {
logger.info("发送的文本内容:{}", text);
try {
mqManager.sendMsg(COUNT_QUEUE_NAME, text);
} catch (Exception e){
e.printStackTrace();
logger.error(e.getMessage());
}
return "SUCESS";
}
@ApiOperation(value="查询单词计数", notes="查询单词计数", produces="application/json")
@ApiImplicitParam(name = "word", value = "单词", paramType = "query", required = true, dataType = "String")
@RequestMapping(value="/queryWordCount", produces={ MediaType.APPLICATION_JSON_UTF8_VALUE }, consumes={ MediaType.APPLICATION_JSON_UTF8_VALUE }, method=RequestMethod.POST)
public String queryWordCount(@RequestBody String word) {
logger.info("查询单词计数:{}", word);
try {
mqManager.sendMsg(QUERY_QUEUE_NAME, word);
} catch (Exception e){
e.printStackTrace();
logger.error(e.getMessage());
}
return "SUCESS";
}
}
本接口示例了 @ApiOperation 和 @ApiImplicitParam 两个注解的使用。
Swagger 通过注解定制接口对外展示的信息,这些信息包括接口名、请求方法、参数、返回信息等。更多注解类型:
- @Api:修饰整个类,描述Controller的作用
- @ApiOperation:描述一个类的一个方法,或者说一个接口
- @ApiParam:单个参数描述
- @ApiModel:用对象来接收参数
- @ApiProperty:用对象接收参数时,描述对象的一个字段
- @ApiResponse:HTTP响应其中1个描述
- @ApiResponses:HTTP响应整体描述
- @ApiIgnore:使用该注解忽略这个API
- @ApiError :发生错误返回的信息
- @ApiImplicitParam:描述一个请求参数,可以配置参数的中文含义,还可以给参数设置默认值
- @ApiImplicitParams:描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
启动 SpringBoot 应用
SpringBoot 启动成功后,访问 http://localhost:8080/swagger-ui.html
展开类维度的接口列表,如 active-mq-producer
,页面会列出该类中定义的所有接口。点击任意接口,可查看该接口的 url 路径、请求类型、参数描述和返回码说明等信息。
点击右上角的 “Try it out!”
按钮,录入请求信息,点击 Execute
按钮完成一次请求调用!
Spring Security 中的配置
Spring Boot 项目中如果集成了 Spring Security,在不做额外配置的情况下,Swagger2 文档会被拦截。解决方法是在 Security 的配置类中重写 configure 方法添加白名单即可:
@Override
public void configure ( WebSecurity web) throws Exception {
web.ignoring()
.antMatchers("/swagger-ui.html")
.antMatchers("/v2/**")
.antMatchers("/swagger-resources/**");
}
参考文章
推荐阅读
-
详解使用spring boot admin监控spring cloud应用程序
-
详解如何在Spring Boot项目使用参数校验
-
Spring Boot 配置随机数的技巧代码详解
-
使用Spirng Boot Admin监控Spring Cloud应用项目
-
超详细的Spring Boot入门笔记(总结)
-
详解Spring/Spring boot异步任务编程WebAsyncTask
-
详解Spring boot/Spring 统一错误处理方案的使用
-
详解如何将已有项目改造为Spring Boot项目
-
Spring Boot 配置大全(小结)
-
Spring Boot 实现Restful webservice服务端示例代码