7. 实现 API 自动生成

目录

[1. pom.xml中引用依赖](#1. pom.xml中引用依赖)

[2. 引入相关的依赖](#2. 引入相关的依赖)

[3. 编写配置类](#3. 编写配置类)

[4. application.yml 中添加配置](#4. application.yml 中添加配置)

[5. API 常用注解](#5. API 常用注解)

[6. 访问 API 列表](#6. 访问 API 列表)

[7. API 导入 Postman](#7. API 导入 Postman)


使用 Springfox Swagger生成 API,并导入 Postman,完成API单元测试。
Swagger 简介:Swagger 是⼀套 API 定义的规范 ,按照这套规范的要求去定义接口及接口相关信息, 再通过可以解析这套规范工具,就可以生成各种格式的接口文档,以及在线接口调试页面,通过自动文档的方式,解决了接口文档更新不及时的问题。
Springfox 简介:是对 Swagger 规范解析并生成文档的⼀个实现。

1. pom.xml中引用依赖

统⼀管理版本,在 properties 标签中加入版本号:

XML 复制代码
<springfox-boot-starter.version>3.0.0</springfox-boot-starter.version>

3.0.0 版本对应 Spring Boot 2.6 之前的版本,但是随着 Spring Boot 的更新 Springfox并没有进行同步的更新,所以存在一些兼容性问题,因此我们选择使用 SpringBoot 2.7.6 版本。

2. 引入相关的依赖

XML 复制代码
<!-- API⽂档⽣成,基于swagger2 -->
<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>

3. 编写配置类

  • 在com.bitejiuyeke.forum.config 包下新建SwaggerConfig.java
  • 解决 SpringBoot 2.6.0 以上与 Springfox3.0.0 不兼容的问题,涉及 SpringBoot 版本升级过程中的一 些内部实现变化,具体说明在修改配置文件部分

将以下代码复制到 SwaggerConfig 类中:

java 复制代码
package com.example.demo.controller;

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配置类
 */
// 配置类
@Configuration
// 开启Springfox-Swagger
@EnableOpenApi
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.demo.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
    // 配置API基本信息
    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("论坛系统API")
                .description("论坛系统前后端分离API测试")
                .contact(new Contact("Test",
                        "https://hello.fprum.com", "1111111111@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));
    }
}

4. application.yml 中添加配置

  • 在 spring 节点下添加 mvc 配置项

由于 SpringBoot 2.6 之后版本把 SpringMVC 路径匹配策略修改为 MatchingStrategy. PATH_PATTERN_PARSER;
而 Springfox-Swagger 还没有更新版本 ,我们暂时先把 路径匹配策略回退到之前的
MatchingStrategy. ANT_PATH_MATCHER

XML 复制代码
 mvc:
   path match:
    matching-strategy: ANT_PATH_MATCHER #Springfox-Swagger兼容性配置

5. API 常用注解

  • @Api: 作用在 Controller 上,对控制器类的说明
    • tags="说明该类的作用,可以在前台界面上看到的注解"
  • @ApiModel: 作用在响应的类上,对返回响应数据的说明
  • @ApiModelProerty:作用在类的属性上,对属性的说明
  • @ApiOperation: 作用在具体方法上,对 API 接口的说明
  • @ApiParam: 作用在方法中的每⼀个参数上,对参数的属性进行说明

6. 访问 API 列表

启动程序,在浏览器中输入网址:http://127.0.0.1:58080/swagger-ui/index.html
可以正常运行并显示接口信息,说明配置成功,此时接口信息已经显示出来了,可以分别针每个接口进测试,具操作按页面指引即可。

点击"测试接口"出现如下图所示:

选择对应的 API 列表,点击"Try it out":

点击 Execute:

图中箭头所指方向即为测试结果。

带有参数的同样可以进行测试:

7. API 导入 Postman

获取 API 地址,打开 Swagger 页面的 API 资源地址并复制:

在 Postman 中导入 url:

接下来输入参数:

相关推荐
一个天蝎座 白勺 程序猿10 分钟前
Python练习(1)Python基础类型操作语法实战:20道实战题解与案例分析(上)
开发语言·python·学习
lightqjx20 分钟前
【数据结构】顺序表(sequential list)
c语言·开发语言·数据结构·算法
巨人张30 分钟前
信息素养Python编程题
开发语言·python
东阳马生架构32 分钟前
订单初版—5.售后退货链路中的技术问题说明文档
java
小小寂寞的城37 分钟前
JAVA策略模式demo【设计模式系列】
java·设计模式·策略模式
阿猿收手吧!1 小时前
【计算机网络】HTTP1.0 HTTP1.1 HTTP2.0 QUIC HTTP3 究极总结
开发语言·计算机网络
JAVA学习通1 小时前
图书管理系统(完结版)
java·开发语言
abigalexy1 小时前
深入Java锁机制
java
paishishaba1 小时前
处理Web请求路径参数
java·开发语言·后端