springboot2.5.6集成swagger3
- 1. 引入依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
- 2. application.yml配置
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
- 启动依赖
@EnableOpenApi //开启swagger支持
- 3. swaggerConfig
package com.springboot.test.config.swagger; 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.oas.annotations.EnableOpenApi; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; /** * @author cf * @date 2022/12/3 18:56 * @description swagger配置类 */ @Configuration @EnableOpenApi //开启swagger支持 public class SwaggerConfig { /** * Docket类是Swagger的配置类,要自定义修改 Swagger 的默认配置信息,我们需要覆盖该对象 * @return */ @Bean public Docket docket(){ //1.以OAS_30标准构建Docket配置类 return new Docket(DocumentationType.OAS_30) //2.配置Swagger接口文档基本信息apiInfo .apiInfo(apiInfo()) //3.select方法开启配置扫描接口的Builder .select() //4.指定要扫描/维护接口文档的包(否则就全部扫描) .apis(RequestHandlerSelectors.basePackage("com.springboot.test.controller")) //5.路径过滤:该Docket-UI展示时,只展示指定路径下的接口文档(any表示都展示) .paths(PathSelectors.any()) .build(); } /** * 配置 Swagger 接口文档的基本信息 * @return */ private ApiInfo apiInfo(){ return new ApiInfoBuilder() //1.接口文档标题 .title("SpringBoot整合Swagger") //2.接口文档描述内容 .description("这里是SpringBoot整合Swagger的详细信息") //3.项目文档迭代版本 .version("9.0") //4.主要联系人信息(姓名name,个人主页url,邮箱email) .contact(new Contact("cf","www.1111.com","1111111@qq.com")) //5.相关许可证信息 .license("The CSDN License") //6.相关许可证链接 .licenseUrl("www.baidu.com") //7.返回构建的ApiInfo对象 .build(); } }
- 4. 启动地址
http://localhost:8080/swagger-ui/index.html#/
- 5. Swagger 注解的使用
4.Swagger Api概述 文章只这里使用到了Swagger提供的注解@ApiOperation,常用的注解还有: (1)@Api:用在类上,说明该类的作用 (2)@ApiOperation:用在方法上,说明方法的作用,标注在具体请求上,value和notes的作用差不多,都是对请求进行说明;tags则是对请求进行分类的,比如你有好几个controller,分别属于不同的功能模块,那这里我们就可以使用tags来区分了。 (3)@ApiImplicitParams:用在方法上包含一组参数说明 (4)@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面。 (5)@ApiResponses:用于表示一组响应 (6)@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息 (7)@ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)表明这是一个被swagger框架管理的model,用于class上 (8)@ApiModelProperty: 这里顾名思义,描述一个model的属性,就是标注在被标注了@ApiModel的class的属性上,这里的value是对字段的描述,example是取值例子,注意这里的example很有用,对于前后端开发工程师理解文档起到了关键的作用,因为会在api文档页面上显示出这些取值来;