SpringBoot3.0集成SpringDoc

• 1. pom配置
• 2. OpenApi配置类
• 3. 使用
• 4. SpringDoc注解与SpringFox对比
• 5. 演示项目

这里为什么要使用SpringDoc呢？是因为集成SpringFox只支持SpringBoot2.x，
而基于Swagger的SpringDoc的社区现在十分活跃，代码也在不断更新。
SpringFox自从2020年7月14号之后就不更新了。

YiYi项目学习教程

1. pom配置

    org.springdoc
    springdoc-openapi-starter-webmvc-ui
    2.0.2

2. OpenApi配置类

这里和Swagger配置类似，主要是配置接口的标题、描述、版本信息、Authorizations权限等。
下面两个分组信息也可以根据项目自身进行配置即可。

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityScheme;

/**
 * SpringDoc 配置类
 *
 * @author Jack魏
 * @since 2023/1/8 16:51
 */
@Configuration
public class OpenApiConfig {
    /**
     * SpringDoc 标题、描述、版本等信息配置
     *
     * @return openApi 配置信息
     */
    @Bean
    public OpenAPI springDocOpenAPI() {
        return new OpenAPI().info(new Info()
                        .title("YiYi API")
                        .description("YiYi接口文档说明")
                        .version("v0.0.1-SNAPSHOT")
                        .license(new License().name("YiYi项目博客专栏")
                                .url("https://blog.csdn.net/weihao0240/category_12166012.html")))
                .externalDocs(new ExternalDocumentation()
                        .description("码云项目地址")
                        .url("https://gitee.com/jack0240/YiYi"))
                // 配置Authorizations
                .components(new Components().addSecuritySchemes("bearer-key",
                        new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer")));
    }

    /**
     * demo 分组
     *
     * @return demo分组接口
     */
    @Bean
    public GroupedOpenApi siteApi() {
        return GroupedOpenApi.builder()
                .group("demo接口")
                .pathsToMatch("/demo/**")
                .build();
    }

    /**
     * sys 分组
     *
     * @return sys分组接口
     */
    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("sys接口")
                .pathsToMatch("/sys/**")
                .build();
    }
}

3. 使用

可以看到注解的方式和Swagger基本上一模一样，就是名字有所变化而已。

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.jack.yiyi.bean.SysUser;
import com.jack.yiyi.service.sys.SysUserService;
import com.jack.yiyi.util.Result;

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;


/**
 * 系统用户Controller控制类
 *
 * @author Jack魏
 * @since 2022-11-12
 */
@Tag(name = "系统用户接口", description = "系统用户接口")
@RestController
@RequestMapping("/sys/user/")
public class SysUserController {
    @Autowired
    private SysUserService sysUserService;

    /**
     * 注册后台系统用户
     *
     * @param sysUser 前端注册信息
     * @return 注册用户信息
     */
    @Operation(summary = "注册接口", description = "输入用户信息进行注册")
    @Parameters({
            @Parameter(name = "account", description = "登录账号", required = true),
            @Parameter(name = "password", description = "密码", required = true)
    })
    @PostMapping("register")
    public Result register(SysUser sysUser) {
        // 登录名参数校验
        if (sysUser.getAccount() == null || "".equals(sysUser.getAccount())) {
            return Result.fail("注册用户名不能为空");
        }
        // 密码参数校验
        if (sysUser.getPassword() == null || "".equals(sysUser.getPassword())) {
            return Result.fail("密码不能为空");
        }

        SysUser user = sysUserService.register(sysUser);
        if (user == null) {
            return Result.fail("注册失败！请更换登录名！");
        }
        return Result.success("注册成功，欢迎您：" + sysUser.getAccount());
    }
}

通过上面的配置之后，启动项目即可，然后访问：
http://127.0.0.1:8181/yiyi/swagger-ui/index.html
因为此项目也配置了Security，所以先输入用户：user、密码：123456

登录

SpringDoc

接口调试

返回封装对象

4. SpringDoc注解与SpringFox对比

官网地址：https://springdoc.org/v2/#migrating-from-springfox

5. 演示项目

https://gitee.com/jack0240/YiYi

YiYi项目