SpringBoot整合Swagger3或Knife4j

SpringBoot整合Swagger3

1、引入Swagger依赖

1.1 老版本引入方式简述（了解）

引入依赖

<!-- 引入swagger3包 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

如果还需要页面更加美观，则再添加依赖（swagger-bootstrap-ui升级后叫做knife4j）。

老版本此时还叫swagger-bootstrap-ui

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

修改配置文件

application.yml文件修改方式

# Swagger的端口和项目端口一致
server:
  port: 9098

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

application.properties文件修改方式

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

访问地址：http://localhost:8080/doc.html

1.2 新版本引入方式

针对Spring Boot 2.x

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.8.0</version>
</dependency>

针对Spring Boot 3.x

<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

默认：Swagger的端口和项目端口一致
并且此时不能用上面说的那个美化包了，只能直接集成Knife4j进行美化

SpringBoot整合Knife4j

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!

gitee地址：https://gitee.com/xiaoym/knife4j

官方文档：https://doc.xiaominfo.com/

预览地址: https://doc.xiaominfo.com/demo/doc.html

参考自：https://doc.xiaominfo.com/docs/quick-start#openapi2
https://doc.xiaominfo.com/docs/action/springboot

1、引入Knife4j的依赖

针对Spring Boot 2.x

Swagger2规范

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>{maven仓库最新版本}</version>
</dependency>

OpenAPI3规范

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>{maven仓库最新版本}</version>
</dependency>

针对Spring Boot 3.x

在Spring Boot 3.x版本中，开发者应该选择OpenAPI3规范来作为应用框架的开发首选方案。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>{maven仓库最新版本}</version>
</dependency>

2、编写yaml配置文件或配置类

两种方式选一种就可以

2.1 方法一：配置yml文件（下面是旧版的代码，不推荐使用yml文件形式配置）

一定要配置好api-rule-resources，否则文档中不会列出接口

knife4j:
  enable: true # 是否开启增强配置
  openapi:
    title: Knife4j官方文档 # 首页 / Openapi数据中的接口文档的标题
    description: "这是文档的描述内容" # 首页 / Openapi数据中的接口文档的简介
    email: email@foxmail.com # Openapi数据中的联系邮箱
    concat: 阿莱德 # 首页 / Openapi数据中的作者
    url: https://联系人.com # Openapi数据中的联系人网站
    version: v1.2 # 首页 / Openapi数据中的接口文档版本
    license: Apache 99.9 # Openapi数据中的许可证
    license-url: https://license-url.com/ # Openapi数据中的许可证url
    terms-of-service-url: https://terms-of-service-url.com/ # 首页 / Openapi数据中的API服务条款
    group:
      test1:
        group-name: default # 首页：分组名称
        api-rule: package # 接口规则，此处表示按照包名进行规则分类
        api-rule-resources: # 针对每个资源（包）的规则配置
          - org.example.springbootlearn # 指定包路径，表示这个包下的接口将按照规则分类（一定要修改为自己的）
  # 开启账户登录模式 
  basic:
    enable: true
    username: admin
    password: 123456

2.2 方法二：编写配置类

2.2.1 旧版

参考：https://doc.xiaominfo.com/docs/features/i18n

import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;  
import io.swagger.annotations.ApiOperation;  
import org.springframework.beans.factory.annotation.Autowired;  
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.service.ApiInfo;  
import springfox.documentation.spi.DocumentationType;  
import springfox.documentation.spring.web.plugins.Docket;  
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;  
  
/**  
 * 配置 Knife4j 接口文档  
 *  
 */  
@Configuration  
@EnableSwagger2WebMvc  
public class Knife4jConfiguration {  
    private final OpenApiExtensionResolver openApiExtensionResolver;  
  
    @Autowired  
    public Knife4jConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {  
        this.openApiExtensionResolver = openApiExtensionResolver;  
    }  
  
  
    @Bean(value = "defaultApi2")  
    public Docket defaultApi2() {  
        String groupName = "yunhu-library";  
        Docket docket = new Docket(DocumentationType.SWAGGER_2)  
                .apiInfo(apiInfo())  
                .groupName(groupName)  
                .select()  
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) 
                .paths(PathSelectors.any())  
                .build()  
                .extensions(openApiExtensionResolver.buildExtensions(groupName));  
        return docket;  
    }  
  
    private ApiInfo apiInfo() {  
        return new ApiInfoBuilder()  
                .description("# swagger-bootstrap-ui-demo RESTful APIs")  
                .termsOfServiceUrl("http://www.library.wiki")  
                .version("1.0")  
                .build();  
    }  
}

2.2.2 新版

package com.dongfangwisdom.projectmanagement.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * 配置 Knife4j 接口文档  
 *  
 */  
@Configuration
@EnableKnife4j
public class Knife4jConfiguration {


    private static final String SERVICE_URL = "http://127.0.0.1:7004/tj4/doc.html";
    private static final String API_INFO_TITLE = "软件接口文档";
    private static final String API_INFO_VERSION = "V1.2";
    private static final String API_INFO_DESCRIPTION = "Api接口列表";
    private static final String API_INFO_LICENSE = "2024年度内部文档,违拷必究.";

    // 系统接口
    @Bean
    public GroupedOpenApi api1() {
        // 要扫描的包，一定要配置好，否则文档中不会列出接口
        String[] packagedToMatch = { "com.dongfangwisdom.projectmanagement" };
        return GroupedOpenApi.builder()
                // 分组名称，使用英文，中文访问异常(使用displayName设置中文名，避免直接使用group设置中文时访问异常)
                .group("admin-api")
                .displayName("01-系统接口") // 使用displayName设置中文接口分组名时，group仍不可或缺
                .packagesToScan(packagedToMatch)
                .build();
    }
  


    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title(API_INFO_TITLE)//  首页 / 主页 / 标题
                        .description(API_INFO_DESCRIPTION) // 首页 / 主页 / 简介
                        .version(API_INFO_VERSION) //首页 / 主页 / 版本
                        .contact(new Contact().name("Keyidea").email("support@keyidea.cn").url("https://联系人.com"))//作者信息
                        .termsOfService("Api服务条款")//首页 / API服务条款
                        .license(new License().name(API_INFO_LICENSE).url(SERVICE_URL))//open选项卡中的API服务条款
                );
    }
}

3、写一个简单的RESTful接口

@Api(tags = "首页模块")
@RestController
public class IndexController {

    @Parameter(name = "name",description = "姓名",required = true)
    @Operation(summary = "向客人问好")
    @GetMapping("/sayHi")
    public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name){
        return ResponseEntity.ok("Hi:"+name);
    }
}

4、如果是引入了SpringSecurity依赖，放行接口即可

.requestMatchers("/swagger**/**").permitAll()
.requestMatchers("/webjars/**").permitAll()
.requestMatchers("/v3/**").permitAll()
.requestMatchers("/swagger-ui/**").permitAll()
.requestMatchers("/doc.html").permitAll()

5、启动Spring Boot工程，访问Knife4j的文档地址

最后，访问Knife4j的文档地址即可查看文档

http://ip:port/doc.html

例如：

http://localhost:48080/doc.html