您现在的位置是:首页 >技术交流 >springboot整合swagger网站首页技术交流
springboot整合swagger
简介springboot整合swagger
概述
- swagger可以方便的生成接口文档,不需要单独书写。
- spring整理swagger简单,编码量低,容易阅读学习。
- 主要步骤:
- springboot引入swagger依赖。
- 配置swagger。
- controller接口上添加注解,标注接口内容。
- 查看。
参考资料
《Spring Boot整合swagger使用教程》,作者:随风行云,地址:https://www.cnblogs.com/progor/p/13297904.html
《SpringBoot整合Swagger3.0》,作者:蓝天⊙白云,地址:https://blog.csdn.net/qq_38747892/article/details/125501031
《IDEA报错之Failed to start bean ‘documentationPluginsBootstrapper‘问题及解决方案》,作者:群鸿,地址:https://blog.csdn.net/mapboo/article/details/121568519
解决HttpSession类过滤问题,地址:https://class.m.imooc.com/qadetail?qid=289940
实施步骤
- 引入swagger依赖
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-spring-web</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
<!-- A1 -->
<exclusions>
<exclusion>
<artifactId>swagger-models</artifactId>
<groupId>io.swagger</groupId>
</exclusion>
</exclusions>
</dependency>
<!-- A2 -->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.6.8</version>
</dependency>
- 代码A1和A2处解决swagger打开页面后自动访问后端接口的问题,改为手动触发。
- 配置swagger
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
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.swagger2.annotations.EnableSwagger2;
import javax.servlet.http.HttpSession;
@Profile("dev") //表明开发环境生效
@Configuration // 标明是配置类
@EnableSwagger2 //开启swagger功能
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2) // DocumentationType.SWAGGER_2 固定的,代表swagger2
//.groupName("分布式任务系统") // 如果配置多个文档的时候,那么需要配置groupName来分组标识
.apiInfo(apiInfo()) // 用于生成API信息
.ignoredParameterTypes(HttpSession.class)//如果参数列表中有 httpSession,在接口文档不显示,这个是过滤指定类 A2
.select() // select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
.apis(RequestHandlerSelectors.basePackage("com.xxx.controller")) // 用于指定扫描哪个包下的接口
.paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档,可以配置这里
.build();
}
/**
* 用于定义API主界面的信息,比如可以声明所有的API的总标题、描述、版本
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("API") // 可以用来自定义API的主标题
.description("") // 可以用来描述整体的API
.termsOfServiceUrl("") // 用于定义服务的域名
.version("1.0") // 可以用来定义版本。
.build(); //
}
}
- Profile注解标明只有在开发环境才起效。
- A2处代码是为了过滤指定类,这里是为了swagger界面中不展示HttpSession参数信息。资料中有@ApiIgnore注解,我没找到。
- 标注接口组
@Api(tags = "模板管理")
@RestController
@RequestMapping("/pq/device")
public class ModelController {
- 标注接口
@ApiOperation(value = "获取模板列表")
@GetMapping("/list")
public Result<Page<ModelVO>> findList(@Valid ModelQueryDTO query) {
- 标注参数,实体
@ApiModel(value="查询模板DTO",description="")
public class ModelQueryDTO
- 标注参数属性,实体中的属性
@ApiModelProperty(value = "id", required = true, example = "")
private Integer id;
- 参数不是实体
@ApiOperation(value = "删除模板")
@ApiImplicitParams({
@ApiImplicitParam(name = "modelId",
value = "模板id",
required = true,
paramType = "query"
)
})
@GetMapping("/delete")
public Result delete(@NotNull(message = "模板id不能为空") Integer modelId)
- paramType常用的path,query,body,form,header等方式,但对于对于非实体类参数的时候,常用的只有path,query,header。path是参数在路径上的,query是url中?后面的,header是请求头中的。
- 返回值如果是实体类也可以仿照第5步和第6步操作。
- 访问查看,地址:http://localhost:8081/swagger-ui/index.html
- 这个不同的版本有区别,如果无效可以试试这个:http://localhost:8080/swagger-ui.html
- 地址中的ip和端口都是整合入工程的ip、端口。
遇到的问题
- spring整合swagger后报错:Failed to start bean ‘documentationPluginsBootstrapper‘。
答:原因是spring和swagger版本不兼容导致的。调整版本号,或者添加配置
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
- HttpSession类对象不想显示在swaggerui接口界面上。
答:配置环境的时候添加过滤,在步骤-第2步中有说明。 - swagger接口文档只在开发环境生效。
答:使用@Profile注解。 - swagger如何关闭自动访问后端接口。
答:降低swagger-models版本,参考步骤-第1步。
风语者!平时喜欢研究各种技术,目前在从事后端开发工作,热爱生活、热爱工作。