基于SpringBoot3从零配置SpringDoc

为了方便调试，更好的服务于前后端分离式的工作模式，我们给项目引入Swagger。

系列文章指路👉

系列文章-基于SpringBoot3创建项目并配置常用的工具和一些常用的类

1. SpringFox

首先想到的肯定是SpringFox

引入之后项目启动报错：
java.lang.TypeNotPresentException: Type javax.servlet.http.HttpServletRequest not present

1. github SpringFox已经两年没有更新了。
2. SpringFox对SpringBoot3.0不适配，要使用必须降低SpringBoot版本，这显然不是我们的风格
   果断弃用。

2. SpringDoc

更新很快，且支持OpenAPI 3、SpringBoot 3。

切换到SpringDoc后有两点不太舒服：

1. 之前使用SpringFox较多，注解一下全换成SpringDoc风格的不太习惯
2. MybatisPlus代码机生成实体类暂不支持SpringDoc注解，生成后需要手动添加（随着表的增多和表结构的复杂化，这部分工作量是很大的），希望苞米豆大大们支持一下。

---

2023-05-10更新： MybatisPlus最新的代码生成器（3.5.3.1）支持了生成SpringDoc注解 🎉

2.1 引入依赖

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

2.2 配置文件

@Configuration
public class YaSwaggerConfig {

    private License license() {
        return new License()
                .name("MIT")
                .url("https://opensource.org/licenses/MIT");
    }

    private Info info(){
        return new Info()
                .title("Ya API")
                .description("A test project for Mr.Ya.")
                .version("v1.0.0")
                .license(license());
    }
    private ExternalDocumentation externalDocumentation() {
        return new ExternalDocumentation()
                .description("这是一个额外的描述。")
                .url("https://shijizhe.github.io/");
    }

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(info())
                .externalDocs(externalDocumentation());
    }
}

2.3 语法

SpringFox	SpringDoc
@Api	@Tag
@ApiOperation(value = “foo”, notes = “bar”)	@Operation(summary = “foo”, description = “bar”)
@ApiParam	@Parameter
@ApiResponse(code = 404, message = “foo”)	@ApiResponse(responseCode = “404”, description = “foo”)
@ApiModel	@Schema
@ApiModelProperty	@Schema
@ApiIgnore	@Parameter(hidden = true)or@Operation(hidden = true)or@Hidden
@ApiImplicitParam	@Parameter
@ApiImplicitParams	@Parameters

2.4 使用示例

一些使用示例：

@Tag 用于标识controller

@Tag(name = "FruitController", description = "水果相关接口")
@Slf4j
@RestController
@RequestMapping("/goods/fruit")
public class FruitController {
}

@Operation 用于标识方法

    @PutMapping("/update")
    @Operation(summary = "update", description = "更新水果信息")
    @Parameter(name = "fruit",description = "需要更新的水果")
    public Object update(Fruit fruit) {
        return fruitService.updateById(fruit);
    }

@Schema 用于标识实体类和实体类的属性

@Schema(description = "水果")
public class Fruit implements Serializable {
    private static final long serialVersionUID = 1L;

    @Schema(description = "主键")
    @TableId(value = "id", type = IdType.AUTO)
    private Long id;

    @Schema(description = "编码")
    private String frCode;
    
    @Schema(description = "名称")
    private String frName;

    @Schema(description = "价格")
    private BigDecimal frPrice;
}

@ApiResponse 用于标识请求的响应

    @GetMapping("/list2")
    @Operation(summary  = "list2", description = "列表查询2")
    @ApiResponse(description = "列表查询用户返回",content = {
            @Content(
                    array= @ArraySchema(schema = @Schema(implementation = YaUser.class))
            )
    })
    public Object list2() {
        // 使用mybatis-plus
        return  yaUserService.list();
    }

@Parameters和@Parameter 用于标识请求参数

@Parameter的name需要和变量的命名一致

    @PutMapping("/update2")
    @Operation(summary = "update2", description = "更新水果信息2")
    @Parameters({
            @Parameter(name = "code",description = "水果编码"),
            @Parameter(name = "name",description = "水果名称"),
            @Parameter(name = "price",description = "水果价格")
    })
    public Object update2( String code, String name, Integer price) {
        UpdateWrapper<Fruit> wrapper = new UpdateWrapper<>();
        wrapper.lambda()
                .eq(Fruit::getFrCode,code)
                .set(Fruit::getFrName,name)
                .set(Fruit::getFrPrice,price);
        return fruitService.update(wrapper);
    }

@Parameter 放到函数形参前面

    @GetMapping("/hello")
    @Operation(summary  = "hello", description = "hello")
    public Object hello(@Parameter(description = "需要打招呼的人",example="xiaoming") String userName) {
        return "hello" + userName;
    }

2.5 使用自带的swagger-ui查看：

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

3. 引入Knife4j

引入Knife4j优化Swagger样式：

3.1 引入依赖

Knife4j提供的starter已经引用springdoc-openapi的jar，应该将SpringDoc的依赖注释掉

<!--       
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.1.0</version>
        </dependency>-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.1.0</version>
        </dependency>

3.2 xml配置

直接使用官网提供的示例即可：

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.ya.boottest

knife4j:
  enable: true
  setting:
    language: zh_cn

3.3 展示

确实比swagger-ui好用和美观！

4. 文档分组

  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.ya.boottest
    - group: 'common'
      paths-to-match: '/common/**'
      packages-to-scan: com.ya.boottest
    - group: 'goods'
      paths-to-match: '/goods/**'
      packages-to-scan: com.ya.boottest