Spring Boot integrates Swagger2 to build API documentation

Arnold Warzenegger of Java 2022-08-06 12:32:11 阅读数:861

springbootintegratesswagger2swagger

本文已参与「新人创作礼」活动,一起开启掘金创作之路.

一、为什么需要使用Swagger?

当下很多公司都采取前后端分离的开发模式,前端和后端的工作由不同的工程师完成.在这种开发模式下,维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率.传统意义上的文档都是后端开发人员手动编写的,相信大家也都知道这种方式很难保证文档的及时性,这种文档久而久之也就会失去其参考意义,反而还会加大我们的沟通成本.而 Swagger 给我们提供了一个全新的维护 API 文档的方式,下面我们就来了解一下它的优点:

  • 代码变,文档变.只需要少量的注解,Swagger 就可以根据代码自动生成 API 文档,很好的保证了文档的时效性.
  • 跨语言性,支持 40 多种语言.
  • Swagger UI 呈现出来的是一份可交互式的 API 文档,我们可以直接在文档页面尝试 API 的调用,省去了准备复杂的调用参数的过程.
  • 还可以将文档规范导入相关的工具(例如 SoapUI), 这些工具将会为我们自动地创建自动化测试.

二、Spring Boot整合Swagger2

1、导入Swagger2依赖

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
复制代码

2、编写Swagger2配置类

@Configuration
@EnableSwagger2
public class Swagger2Configuration {
@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInfo())
.select()
// 要扫描的API(Controller)基础包
.apis(RequestHandlerSelectors.basePackage("com.yiidian"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInfo() {
Contact contact = new Contact("腾腾","","");
return new ApiInfoBuilder()
.title("SpringBoot整合Swagger2构建API文档")
.description("The article management servicesapi")
.termsOfServiceUrl("http://www.baidu.com")
.contact(contact)
.version("1.0.0").build();
}
}
复制代码
  • @EnableSwagger2 注解表示开启SwaggerAPI文档相关的功能
  • 在apiInfo方法中配置接口文档的title(标题)、描述、termsOfServiceUrl(服务协议)、版本等相关信息
  • 在createRestApi方法中,basePackage表示扫描哪个package下面的Controller类作为API接口文档内容范围
  • 在createRestApi方法中,paths表示哪一个请求路径下控制器映射方法,作为API接口文档内容范围

Then start the project the following error happens:

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:181) ~[spring-context-5.3.18.jar:5.3.18]
at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:54) ~[spring-context-5.3.18.jar:5.3.18]
at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:356) ~[spring-context-5.3.18.jar:5.3.18]
at org.springframework.context.support.DefaultLifecycleProcessor$$Lambda$615/1559929085.accept(Unknown Source) ~[na:na]
at java.lang.Iterable.forEach(Iterable.java:75) ~[na:1.8.0_31]
复制代码

原因是SpringBoot的版本与Swagger2的版本不兼容导致.可以适当下调SpringBoot的版本,比如我这里把2.6.6版本降到2.5.6

<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.6.6</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
复制代码

The modified start was no problem!做一下访问验证:http://localhost:8888/swagger-ui.html ,如下:

506e01cfdc33fbe9ef67072b7a1a0659.png

swagger不仅提供了静态的接口文档的展示,还提供了执行接口方法测试的功能.在下图中填入接口对应的参数,点击“try it out"就可以实现接口请求的发送与响应结果的展示.

74f7cc8c5095a0df8edefe82742798a8.png

三、Swagger2的常见注解

通常情况下Controller类及方法书写了swagger注解,就不需要写java注释了.写法如下:

 @ApiOperation(value = "添加文章", notes = "添加新的文章", tags = "Article",httpMethod = "POST")
@ApiImplicitParams({
@ApiImplicitParam(name = "title", value = "文章标题", required = true, dataType = "String"),
@ApiImplicitParam(name = "content", value = "文章内容", required = true, dataType = "String"),
@ApiImplicitParam(name = "categoryName", value = "文章类别", required = true, dataType = "String")
})
@ApiResponses({
@ApiResponse(code=200,message="成功",response=ResponseResult.class),
})
@PostMapping("/article")
public @ResponseBody ResponseResult saveArticle2(
@RequestParam(value="title") String title, //参数1
@RequestParam(value="content") String content,//参数2
@RequestParam(value="categoryName") String categoryName//参数3
) {
log.info("添加文章");
return ResponseResult.success();
}
复制代码

swagger注释添加完成之后,接口文档变成如下的样子:

50fa2cb3b91c43bf004a31e4b5ab353e.png

ApiModel注解的用法:

@Data
@ApiModel(value = "通用响应数据结构类")
public class ResponseResult {
@ApiModelProperty(value="请求是否处理成功")
private boolean isok; //请求是否处理成功
@ApiModelProperty(value="请求响应状态码",example="200、400、500")
private int code; //请求响应状态码(200、400、500)
@ApiModelProperty(value="请求结果描述信息")
private String message; //请求结果描述信息
@ApiModelProperty(value="请求结果数据")
private Object data; //请求结果数据(通常用于查询操作)
.....
}
复制代码

Document display as follows:

701a08709cd0bfd3bad24693cdde3c58.png

四、生产环境禁用Swagger2

我们的文档通常是在团队内部观看及使用的,不希望发布到生产环境让用户看到.

  • 禁用方法1:使用注解@Profile({"dev","test"}) 表示在开发或测试环境开启,而在生产关闭.
  • 禁用方法2:使用注解@ConditionalOnProperty(name = "swagger.enable", havingValue = "true") 然后在测试配置或者开发配置中 添加 swagger.enable = true 即可开启,生产环境不填则默认关闭Swagger.
copyright:author[Arnold Warzenegger of Java],Please bring the original link to reprint, thank you. https://en.javamana.com/2022/218/202208061228143683.html