基于SpringBoot3从零配置SpringDoc

一、SpringFox

• github SpringFox 已经停止更新了。
• SpringFox 对 SpringBoot3.0 不适配，要使用必须降低 SpringBoot的版本。

---

二、SpringDoc

• SpringDoc，它可简化 API 文档的生成和维护，这些文档基于 OpenAPI 3 规范，适用于 Spring Boot 3.x 应用程序。Spring Boot 3.x 要求使用 springdoc-openapi version 2 及以上。

  <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.1.0</version>
  </dependency>
  

---

三、Open API 规范

• Open API 即开放 API，也称开放平台。 所谓的开放 API（OpenAPI）是服务型网站常见的一种应用，网站的服务商将自己的网站服务封装成一系列 API（Application Programming Interface，应用编程接口）开放出去，供第三方开发者使用，这种行为就叫做开放网站的 API，所开放的 API 就被称作 OpenAPI（开放 API ）。
• OpenAPI 规范官方文档
  • https://openapi.apifox.cn/

---

四、SpringBoot3配置Knife4j

• Knife4j 是一个集 Swagger2 和 OpenAPI3 为一体的增强解决方案。Knife4j 相当于是对 SpringDoc UI 优化的一个组件。
• Knife4j就是一个接口文档工具，可以看作是Swagger的升级版，但是界面比Swagger更好看，功能更丰富。

1.官方参考文档

• Knife4j官方网站
  • https://doc.xiaominfo.com/
• 官方文档（快速开始）
  • 快速开始
• 官方文档（Knife4j版本参考）
  • Knife4j 版本参考

2.添加依赖

 <!-- 生成 API 接口文档的组件 -->
 <dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
     <version>4.4.0</version>
 </dependency>

3.添加配置项

• 官方文档（详细配置）：
  • 3.1 增强模式

  server.port: 8800  # 设置端口号
  server:
    servlet:
      context-path: /test # 设置服务器的访问路径
  springdoc:
    swagger-ui:
      path: /swagger-ui.html
      tags-sorter: alpha
      operations-sorter: alpha
    api-docs:
      path: /v3/api-docs
    group-configs:
      - group: test
        paths-to-match: '/**'
        # 生成文档所需的扫包路径，一般为启动类目录
        packages-to-scan: com.gdb.test
  #knife4j 增强配置
  knife4j:
    #是否启用增强设置
    enable: true
    #开启生产环境屏蔽
    production: false
    #是否启用登录认证
    basic:
      enable: true
      username: admin
      password: 123456
    setting:  # 前端UI的个性化配置属性
      language: zh_cn # 显示语言中文
      enable-version: true
      enable-swagger-models: true # 是否显示界面中SwaggerModel功能
      swagger-model-name: SwaggerModel2  # 重命名SwaggerModel名称,默认
      enable-document-manage: true # 是否显示界面中"文档管理"功能
  

4.设置文档首页

import io.swagger.v3.oas.models.ExternalDocumentation;
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.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jConfig {
    @Bean
    public OpenAPI myOpenAPI() {
        return new OpenAPI()
                // 接口文档标题
                .info(new Info().title("程序员API")
                        // 接口文档简介
                        .description("这是基于Knife4j OpenApi3的接口文档")
                        .termsOfService("https://blog.csdn.net/weixin_65032328?type=blog")
                        // 接口文档版本
                        .version("v1.0.0")
                        // 接口文档协议
                        .license(new License()
                                .name("许可协议")
                                .url("https://blog.csdn.net/weixin_65032328?type=blog"))
                        // 开发者联系方式
                        .contact(new Contact()
                                .name("迷人的小宝")
                                .email("dingbaogui8@gmail.com")
                                .url("https://blog.csdn.net/weixin_65032328?type=blog")))
                .externalDocs(new ExternalDocumentation()
                        .description("小宝945博客")
                        .url("https://blog.csdn.net/weixin_65032328?type=blog"));
    }
}

5.编写控制器

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "项目首页", description = "用户首先访问的页面")
@RestController
public class HelloController {
    @Parameters ({  //详细说明每一个参数
            @Parameter(name = "name", description = "请求人姓名", required = true)
    })
    @Operation (summary = "简短描述", description = "更详细的描述")
    @PostMapping("/calldingbao")
    public String hello(String name){
        return name + "好啊，我是xiu宝哦！！！";
    }
}

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/user")
@Tag(name = "用户管理", description = "用户数据增删改查")
public class UserController {
    @Operation(
            summary = "根据ID，查询用户",
            parameters = {
                    @Parameter(name = "id", description = "用户的唯一标识 id", required = true, in = ParameterIn.PATH)
            },
            responses = {
                    @ApiResponse(responseCode = "200", description = "成功", content = @Content(mediaType = "application/json")),
                    @ApiResponse(responseCode = "400", description = "错误", content = @Content(mediaType = "application/json"))
            }
    )
    @GetMapping("/{id}")
    public Integer getUserById(@PathVariable int id) {
        return id;
    }
}

6.文档展示

• 此时运行项目，例如：http://127.0.0.1:8080/test/doc.html
  
  
  

---

五、参考

[1]. 基于SpringBoot3从零配置SpringDoc
[2]. Swagger3 GET请求，使用对象接收 Query 参数，注解怎么写？

---