使用了最新 SpringBoot 版本的朋友们在使用 swagger 时一定都碰到了很多烦恼，各种报错。废话不多说，既然你已经看到了这里就说明你已经查阅了很多资料，对swagger有了一定的了解。话不多说，直接上菜。
| 造成问题的原因
当然咯，上菜之前咱还是得讲解一下，为何频频出错；原因很简单，随着时间的推移，springboot 一直在更新迭代，而 swagger 已经1年多没有再进行升级（当前时间：北京时间3月6日17：38分），因此版本已经不再兼容；
上菜
我当前所使用的 springboot 及 springcloud 对应的版本
父项目做了版本管理
| 需要在项目中添加的springdoc依赖
| yml文件配置
#springdoc接口文档指定接口包扫描
springdoc:
packages-to-scan: com.xxxxxxxx
#或者指定访问接口路径扫描
# paths-to-match: /api/user/**
只需扫描sb启动类下的包即可
| 配置类
项目中添加配置类，配置类的详解查看注释即可
package com.yangdaxian.payment.config;
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;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* http://127.0.0.1:9090/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/
*
* @ClassName SpringDocConfig
* @Description TODO /v3/api-docs
* @Author yangdaxian
* @DATE 2022/2/23 09:46:16
* @Version 1.0
*/
@Configuration
public class SpringDocConfig {
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(info())
/*添加对JWT对token的支持(本步骤可选) 在添加OpenApiConfig类上添加Components信息：然后在OpenApi中注册Components:*/
.components(components())
.externalDocs(externalDocumentation());
}
private License license() {
return new License()
.name("MIT")
.url("https://opensource.org/licenses/MIT");
}
private Info info() {
return new Info()
.title("Benjamin Yang's Open API")
.description("Benjamin Yang")
.version("v0.0.1")
.license(license());
}
private ExternalDocumentation externalDocumentation() {
return new ExternalDocumentation()
.description("Benjamin Yang's Blog")
.url("https://blog.csdn.net/m0_55710969?spm=1001.2014.3001.5343");
}
/* 添加对JWT对token的支持(本步骤可选)
在添加OpenApiConfig类上添加Components信息：*/
private Components components() {
return new Components()
.addSecuritySchemes("bearer-key", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT"));
}
/*然后在OpenApi中注册Components:*/
/* @Bean
public OpenAPI springShopOpenAPI2() {
return new OpenAPI()
.info(info())
.components(components())
.externalDocs(externalDocumentation());
}
*/
// /*在需要使用Authorization的接口上添加：*/
// @Operation(security = { @SecurityRequirement(name = "bearer-key") })
}
使用姿势
很简单，只需要几个注解即可轻松搞定；
| 实体类api文档注解
这里可以看到，使用的还是swagger3包中的内容。
ps：这是码友们对它的社区版升级啦，并非官方，但非常好用哦
实体类的相关注解 ：如图所示
更多使用方式就需要点进注解自己参考啦
| Controller控制层 / 接口方法层
同样，还是导入的swagger3的包，这里仅做几个重要注解参数的使用，更多姿势还请诸位亲自进入接口类解锁；如图所示：
接下来启动项目，访问
127.0.0.1:9090/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#/
即可看到如下图所示的操作文档说明啦~
查看方法，也可以像postman一样测试哦
实体类效果如图
关于新版 springboot 整合 springdoc 到这里便宣告结束啦，祝 玩的愉快！
Thanks
相关阅读
您阅读本篇文章共花了：
发表评论