Spring boot swagger 引入以及后续使用 Knife4j 替换swagger

news2024/11/14 14:57:00

swagger配置

swagger 引入jar包

pom.xml 添加对应的 swagger 信息

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>

swagger 配置配置类

添加对应的 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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration // 标明是配置类
@EnableSwagger2 //开启swagger功能
//@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // DocumentationType.SWAGGER_2 固定的，代表swagger2
//                .groupName("分布式任务系统") // 如果配置多个文档的时候，那么需要配置groupName来分组标识
                .apiInfo(apiInfo()) // 用于生成API信息
                .select() // select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
                .apis(RequestHandlerSelectors.basePackage("org.gateway.controller")) // 用于指定扫描哪个包下的接口
                .paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档，可以配置这里
                .build();
    }

    /**
     * 用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("端口对接项目API") //  可以用来自定义API的主标题
                .description("中间件API管理") // 可以用来描述整体的API
                .termsOfServiceUrl("") // 用于定义服务的域名
                .version("1.0") // 可以用来定义版本。
                .build(); //
    }
}

swagger 注解

@Api(value = "用户管理", description = "用户管理API")
@Api 注解有许多属性可以使用，其中 value 和 description 是两个常用的属性。
value: 通常用于指定 API 的名称。
description: 用于描述这个 API 的功能
@Operation(summary = "普通body请求")
@ApiOperation(value = "查询全部设备配置解析类")
@ApiOperation 注解通常用于方法级别，用来描述一个特定的操作或者方法的功能。value 属性是 @ApiOperation 中的一个重要属性，用来简短地描述该操作的目的。

显示 api 文件信息显示

在这里插入图片描述

swagger 地址信息

http://localhost:8080/swagger-ui.html

knife4j 配置

Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案

导入 knife4j jar 包，并注释调 swagger 引入的jar包，因为 knife4j已经

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<!--在引用时请在maven中央仓库搜索3.X最新版本号-->
	<version>3.0.2</version>
</dependency>

注释 EnableSwagger2 使用 EnableOpenApi 就可以启用 knife4j 信息了

package org.gateway.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration // 标明是配置类
//@EnableSwagger2 //开启swagger功能
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // DocumentationType.SWAGGER_2 固定的，代表swagger2
//                .groupName("分布式任务系统") // 如果配置多个文档的时候，那么需要配置groupName来分组标识
                .apiInfo(apiInfo()) // 用于生成API信息
                .select() // select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
                .apis(RequestHandlerSelectors.basePackage("org.gateway.controller")) // 用于指定扫描哪个包下的接口
                .paths(PathSelectors.any())// 选择所有的API,如果你想只为部分API生成文档，可以配置这里
                .build();
    }

    /**
     * 用于定义API主界面的信息，比如可以声明所有的API的总标题、描述、版本
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("端口对接项目API") //  可以用来自定义API的主标题
                .description("中间件API管理") // 可以用来描述整体的API
                .termsOfServiceUrl("") // 用于定义服务的域名
                .version("1.0") // 可以用来定义版本。
                .build(); //
    }
}

knife4j注解

@Tag(name = "body参数")
@Tag 注解可以用来对 API 进行分组，并且为每个分组提供一个描述性的标签。这对于在生成的 API 文档中组织和导航是非常有用的。
@Operation(summary = "普通body请求")
@Operation 注解用于描述单个 API 操作的详细信息，如它的摘要、描述、请求体等。