【Spring Boot】SpringBoot 2.6.6 集成 SpringDoc 1.6.9 生成swagger接口文档


前言

springfox现状
springdoc现状

之前常用的SpringFox在2020年停止更新了,新项目集成SpringFox出来一堆问题,所以打算使用更活跃的SpringDoc,这里简单介绍一下我这边SpringBoot2.6.6集成SpringDoc1.6.9的demo。


一、SpringDoc是什么?

官网链接

二、使用步骤

1.引入库

maven为例:

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

2.配置类

代码如下(示例):

package com.yhcookie.demo.config; 

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * OpenAPI swagger 配置
 *
 * @author yhcookie
 * @date 2023-08-25
 */
@Configuration
public class OpenApiConfig {

    /**
     * 配置API信息
     * @return
     */
    @Bean
    public OpenAPI demoOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("YHCookie API")
                        .description("springDoc demo API")
                        .version("v1.0.0")
                        // 若想增加其他API信息项,可参考官网
                );
    }

    /**
     * 配置过滤规则
     * 若不配置该GroupedOpenApi, 默认扫描所有接口并生成文档
     * @return
     */
    @Bean
    public GroupedOpenApi demoGroupedOpenApi() {
        return GroupedOpenApi.builder()
                .group("group1") // 分组名,可建多个不同分组,分别扫描不同位置接口
                .pathsToMatch("/controller1/**")
                // 接口过滤,据此增加接口扫描规则(扫描@Operation注解标注的接口)。想皮一下的话,亦可自定义注解
                .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Operation.class)) 
                .build();
    }
}

3.访问测试

默认路径:
UI界面 http://localhost:9527/swagger-ui/index.html

在这里插入图片描述
json界面 http://localhost:9527/v3/api-docs
UI的展示其实就是读取该json展示的
json


总结

我这边也是刚用不久,使用中有问题可以在这交流一下。

其他配置

# 是否启用(默认启用,生产可配置false关闭)
springdoc.swagger-ui.enabled=true
# UI界面
springdoc.swagger-ui.path=/swagger-ui.html

立个Flag

翻译一下官方文档…