主页 > 其他 >

配置Api自动生成

其他
2025-09-08 08:24:02

我的飞书: rvg7rs2jk1g.feishu /docx/TVlJdMgYLoDJrsxAwMgcCE14nxt

使用Springfox Swagger生成API，并导入Postman，完成API单元测试

Swagger: 是一套API定义的规范，按照这套规范的要求去定义接口及接口相关信息，再通过可以解析这套规范工具，就可以生成各种格式的接口文档，以及在线接口调试页面，通过自动文档的方式，解决了接口文档更新不及时的问题。

Springfox: 是对Swagger规范解析并生成文档的一个实现。

代码配置

因为 Springfox 版本(3.0) 的问题,他的版本只有在 springBoot 2.5x能够进行使用,如果我们这里使用springBoot 2.7x及以上就会出现兼容性问题,此时我们就要进行一些适配操作

这里我使用的springBoot版本为 2.7.6

我们需要在 pom 文件中加入对应依赖

统一管理版本,在properties标签中加入版本号  <springfox-boot-starter.version>3.0.0</springfox-boot-starter.version>

引入依赖  <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>${springfox-boot-starter.version}</version> </dependency>  <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency>

编写配置类

将以下代码添加至项目中

import org.springframework.boot.actuate.autoconfigure.endpoint.web.CorsEndpointProperties; import org.springframework.boot.actuate.autoconfigure.endpoint.web.WebEndpointProperties; import org.springframework.boot.actuate.autoconfigure.web.server.ManagementPortType; import org.springframework.boot.actuate.endpoint.ExposableEndpoint; import org.springframework.boot.actuate.endpoint.web.*; import org.springframework.boot.actuate.endpoint.web.annotation.ControllerEndpointsSupplier; import org.springframework.boot.actuate.endpoint.web.annotation.ServletEndpointsSupplier; import org.springframework.boot.actuate.endpoint.web.servlet.WebMvcEndpointHandlerMapping; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.env.Environment; import org.springframework.util.StringUtils; 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; import java.util.ArrayList; import java.util.Collection; import java.util.List; // 配置类 @Configuration // 开启Springfox-Swagger @EnableOpenApi //生成 API 功能 public class SwaggerConfig { /** * Springfox-Swagger基本配置 * @return */ @Bean public Docket createApi() { Docket docket = new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.forum.controller")) //填写自己项目中的controller包路径 .paths(PathSelectors.any()) .build(); return docket; } // 配置API基本信息,以下信息都为自定义信息 private ApiInfo apiInfo() { ApiInfo apiInfo = new ApiInfoBuilder() .title("") //标题 .description("") //描述 .contact(new Contact("name", "url", "email")) .version("1.0") .build(); return apiInfo; } /** * 解决SpringBoot 2.6.0以上与Swagger 3.0.0 不兼容的问题 * 复制即可 **/ @Bean public WebMvcEndpointHandlerMapping webEndpointServletHandlerMapping(WebEndpointsSupplier webEndpointsSupplier, ServletEndpointsSupplier servletEndpointsSupplier, ControllerEndpointsSupplier controllerEndpointsSupplier, EndpointMediaTypes endpointMediaTypes, CorsEndpointProperties corsProperties, WebEndpointProperties webEndpointProperties, Environment environment) { List<ExposableEndpoint<?>> allEndpoints = new ArrayList(); Collection<ExposableWebEndpoint> webEndpoints = webEndpointsSupplier.getEndpoints(); allEndpoints.addAll(webEndpoints); allEndpoints.addAll(servletEndpointsSupplier.getEndpoints()); allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints()); String basePath = webEndpointProperties.getBasePath(); EndpointMapping endpointMapping = new EndpointMapping(basePath); boolean shouldRegisterLinksMapping = this.shouldRegisterLinksMapping(webEndpointProperties, environment, basePath); return new WebMvcEndpointHandlerMapping(endpointMapping, webEndpoints, endpointMediaTypes, corsProperties.toCorsConfiguration(), new EndpointLinksResolver(allEndpoints, basePath), shouldRegisterLinksMapping, null); } private boolean shouldRegisterLinksMapping(WebEndpointProperties webEndpointProperties, Environment environment, String basePath) { return webEndpointProperties.getDiscovery().isEnabled() && (StringUtils.hasText(basePath) || ManagementPortType.get(environment).equals(ManagementPortType.DIFFERENT)); } }

修改配置文件

在yml文件中加入新的配置,这里必须加入!!不然会出现不适配的问题,因为使用的SpringBoot相对于Springfox来说是高版本

spring: mvc: path match: matching-strategy: ant_path_matcher

API常用注解以及使用方法 @Api

作用在 Controller 上,对控制器类进行说明

tags = " 说明该类的作用,可以在前台界面上看到的注释 "

@ApiModel

作用在相应的类上,对返回响应数据的说明

@ApiModelProperty

作用在类的属性上,对属性的说明,也就是具体的对象上

@ApiOperation

作用在具体的方法上,对API接口的说明