每一个成功人士的背后,必定曾经做出过勇敢而又孤独的决定。
放弃不难,但坚持很酷~
今天来说一下 Spring boot 如何集成 Swagger 2,虽然网上有很多这样的教程,但觉得还是应该自己梳理一下,这样对知识的掌握比较牢靠。另外文章中也有我在开发中遇到的问题及解决方法,统一记录下来。 真的比 postman 省心,对于前后端联调、测试、用户来说都很便利。
1、添加 pom.xml 文件依赖
<!-- swagger ui -->
<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>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.22</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.22</version>
</dependency>
2、添加 Swagger java 配置
package com.hollysys.hollicube.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.*;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author create17
* @date 2020/6/3
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.hollysys.hollicube.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 隐藏UI上的Models模块
*/
@Bean
public UiConfiguration uiConfig() {
return UiConfigurationBuilder.builder()
.deepLinking(true)
.displayOperationId(false)
// 隐藏UI上的Models模块
.defaultModelsExpandDepth(-1)
.defaultModelExpandDepth(0)
.defaultModelRendering(ModelRendering.EXAMPLE)
.displayRequestDuration(false)
.docExpansion(DocExpansion.NONE)
.filter(false)
.maxDisplayedTags(null)
.operationsSorter(OperationsSorter.ALPHA)
.showExtensions(false)
.tagsSorter(TagsSorter.ALPHA)
.validatorUrl(null)
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("访问clientid管理、元数据管理、日志管理")
// .description("")
// .version("1.0")
// .contact(new Contact("","",""))
// .license("")
// .licenseUrl("")
.build();
}
/**
* 防止@EnableMvc把默认的静态资源路径覆盖了,手动设置的方式
*
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// 解决静态资源无法访问
registry.addResourceHandler("/**")
.addResourceLocations("classpath:/static/");
// 解决swagger无法访问
registry.addResourceHandler("/swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
// 解决swagger的js文件无法访问
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
分析上述配置,我们需要在 java 类上指明 @Configuration、@EnableSwagger2 注解。
另外还需要指定 controller 的包路径。如果需要隐藏 Swagger ui 上的 Models 模块,则需要上面的 uiConfig() 方法。
为了防止 @EnableMvc 把默认的静态资源路径覆盖,还需要上面的 addResourceHandlers() 方法。
紧接着,我们就可以启动项目了,Swagger 2 ui 地址为:http://ip:port/swagger-ui.html 。
参考博客:https://www.cnblogs.com/fengli9998/p/7921601.html
注解 @ApiModel 和 @ApiModelProperty 是作用在 javaBean 上的,可以起解释说明,是否必选,是否隐藏的作用。在 swagger-ui 页面上的体现形式如下图所示:
@Api、@ApiOperation、@ApiParam、@ApiIgnore、@ApiImplicitParams 都是作用在 controller 层的注解。如下图所示:
关于 java 中常见的对象类型简述(DO、BO、DTO、VO、AO、PO)可参考:https://blog.csdn.net/uestcyms/article/details/80244407 。
当有多个 requestparam 参数的时候,我们用 DTO 对象接收参数比较方便,用 DTO 对象来精准无冗余地接收请求参数。
可能这里有朋友会疑问,为什么不用 PO 来接收请求参数呢?
因为 PO 中可能存在冗余字段,如果用 PO 来接收参数的话,冗余字段也会在 Swagger ui 页面上显示,用户体验并不好,所以我们用 DTO 来接收请求参数。
同理,为了避免返回给前端的数据存在冗余字段(即不需要展示的字段),我们可以使用 VO 来接收数据返回给前端进行交互。
扫码关注腾讯云开发者
领取腾讯云代金券
Copyright © 2013 - 2025 Tencent Cloud. All Rights Reserved. 腾讯云 版权所有
深圳市腾讯计算机系统有限公司 ICP备案/许可证号:粤B2-20090059 深公网安备号 44030502008569
腾讯云计算(北京)有限责任公司 京ICP证150476号 | 京ICP备11018762号 | 京公网安备号11010802020287
Copyright © 2013 - 2025 Tencent Cloud.
All Rights Reserved. 腾讯云 版权所有