一、前言

网上查看了大量资料，发现SpringBoot3+jdk17的情况下，swagger的V2和V3都是不行的。果断转用spring官方出品的springdoc-openapi。在使用springdoc-openapi的时候也有很多坑，首先springdoc-openapi的v1.x.x版本也是不行的，springdoc-openapi的版本必须是v2.x.x以上。

官网链接：

二、入门配置

1、改pom

我的示例Demo项目只引入了很简单的一些东西。下面的两个jar包，第一个是必须导入的，而且一定得在2版本以上。

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

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

2、写Controller案例

2.1不用其他配置

OpenApiConfig这种配置完全可以不用做，application.yml也可以完全不用配置。默认引入pom文件以后，写好Controller就可以用了。

package com.zt.controller;

import com.zt.framework.web.CommonResult;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Slf4j
@Tag(name = "hello")
public class HelloController {
          
   

    @GetMapping("/hello")
    @Operation(summary = "hello", description = "hello")
    public CommonResult<String> hello(){
          
   
        int a = 1/0;
        log.info("hello!!!");
        return CommonResult.successMessage("hello!!!");
    }

}

2.2注意注释区别

@Api -> @Tag
@ApiIgnore -> @Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden
@ApiImplicitParam -> @Parameter
@ApiImplicitParams -> @Parameters
@ApiModel -> @Schema
@ApiModelProperty(hidden = true) -> @Schema(accessMode = READ_ONLY)
@ApiModelProperty -> @Schema
@ApiOperation(value = "foo", notes = "bar") -> @Operation(summary = "foo", description = "bar")
@ApiParam -> @Parameter
@ApiResponse(code = 404, message = "foo") -> @ApiResponse(responseCode = "404", description = "foo")

3、检验测试

访问地址swagger-ui风格： http://server:port/context-path/swagger-ui.html 访问地址swagger-json风格： http://server:port/context-path/v3/api-docs

我这边个人swagger-ui风格地址： http://localhost:8888/swagger-ui/index.html 我这边个人swagger-json风格地址： http://localhost:8888/v3/api-docs 导入apifox也完全没问题，本身就是OpenApi3

三、加强配置

1、方式一：引入OpenApiConfig

参考大神链接：

这边还能配置很多东西。常见的api分组等等，参考上面大神链接。

2、方式二：配置application.yml

springdoc:
  api-docs:
    # 是否开启接口文档
    enabled: true
  swagger-ui:
    # 持久化认证数据，如果设置为 true，它会保留授权数据并且不会在浏览器关闭/刷新时丢失
    persistAuthorization: true

yml这边应该还有很多其他配置。详细见前言的官网说明。