实现API自动生成

原创于 2025-07-02 21:48:23 发布 · 867 阅读

18 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#java #ide

1.背景：

我们在测试我们写的后端接口的时候，通常要一个一个的用postman或者是浏览器去根据我们的映射去测试，这样测的接口少还好，但工程量一大就贼麻烦所以，我们这里引入一个API自动生成的插件Springfox

Swagger简介：Swagger是⼀套API定义的规范，按照这套规范的要求去定义接及接相关信息，再通过可以解析这套规范⼯具，就可以⽣成各种格式的接⽂档，以及在线接调试⻚⾯，通过⾃动⽂档的⽅式，解决了接⽂档更新不及时的问题。

Springfox简介：是对Swagger规范解析并⽣成⽂档的⼀个实现。

Springfox⽂档：http://springfox.github.io/springfox/docs/snapshot/

2.用法：

1.pom.xml中引⽤依赖 • 统⼀管理版本

在properties标签中加⼊版本号：

<springfox-boot-starter.version>3.0.0springfox-boot-starter.version>

引⼊相关依赖:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>${springfox-boot-starter.version}</version>
</dependency>
<!-- SpringBoot健康监控 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

2.编写配置类

• 在org.example.forum.config包下新建SwaggerConfig.java

• 解决SpringBoot2.6.0以上与Springfox3.0.0不兼容的问题，涉及SpringBoot版本升级过程中的⼀些内部实现变化，具体说明在修改配置⽂件部分

• 复制以下代码：

package org.example.forum.config;
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;

/**
 * Swagger配置类
 *
 * @Author ⽐特就业课
 */
// 配置类
@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("org.example.forum.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
    // 配置API基本信息
    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("茶茶论坛系统API")
                .description("茶茶论坛系统前后端分离API测试")
                .contact(new Contact("Bit Tech",
                        "https://edu.bitejiuyeke.com", "1598896550@qq.com"))
                .version("1.0")
                .build();
        return apiInfo;
    }
    /**
     * 解决SpringBoot 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));
    }

    }

3.application.yml中添加配置

• 在spring节点下添加mvc配置项由于SpringBoot2.6之后版本把SpringMVC路径匹配策略修改为 MatchingStrategy.PATH_PATTERN_PARSER; ⽽Springfox-Swagger还没有更新版本，我们暂时先把路径匹配策略回退到之前的 MatchingStrategy.ANT_PATH_MATCHER

mvc:
  pathmatch:
    matching-strategy: ANT_PATH_MATCHER #Springfox-Swagger?????

4.API常⽤注解

• @Api:作⽤在Controller上，对控制器类的说明 ◦ tags="说明该类的作⽤，可以在前台界⾯上看到的注解"

• @ApiModel: 作⽤在响应的类上，对返回响应数据的说明

• @ApiModelProerty:作⽤在类的属性上，对属性的说明

• @ApiOperation:作⽤在具体⽅法上，对API接的说明

• @ApiParam:作⽤在⽅法中的每⼀个参数上，对参数的属性进⾏说明

5.访问API列表

• 启动程序，浏览器中输⼊地址：http://127.0.0.1:58080/swagger-ui/index.html，可以正常并显⽰接⼝信息，说明配置成功，此时接⼝信息已经显⽰出来了，可以分别针每个接⼝进⾏测试，具体操作按⻚⾯指引即可。（我的server：port设的是58080你们用的时候改成你自己的）