本次主要是配置关于springdoc-openapi-starter-webmvc-ui中的过程和遇到的一些问题;
首先在搭建好的springboot中添加maven依赖:
<!-- 加入 springdoc 依赖 -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.2.0</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
<version>2.2.0</version>
</dependency>
依赖版本可以自行调整;第一个依赖是必要项;
添加后启动就可以直接访问了,默认的访问地址(端口号修改为自己的项目端口号):http://localhost:8080/swagger-ui/index.html
正常情况下就可以看到一个这样的访问页面了;
如果访问出现404可以先排查以下几项:
1、是否配置了访问拦截;
2、项目是否有准确启动;
3、去添加相应的配置项;
如果出现可以正常打开页面,但是展示的是swagger的官网页面,非自己的系统接口,可能是因为框架配置了统一封装返回导致了http://localhost:8080/v3/api-docs无法正常访问返回;
错误样例:
解决方案可移步springdoc的使用日记之解决统一返回封装的壁垒查看是否能提供解决思路~
如果想要自定义一些访问地址或者其他参数可以在配置文件或yml中添加以下设置:
# 开启OpenApi接口
springdoc.api-docs.enabled=true
# 自定义路径,默认为 "/v3/api-docs"
springdoc.api-docs.path=/v3/api-docs
# 开启swagger界面,依赖OpenApi,需要OpenApi同时开启
springdoc.swagger-ui.enabled=true
# 自定义路径,默认为"/swagger-ui/index.html"
springdoc.swagger-ui.path=/swagger-ui/index.html
然后如果还想要自定义访问页面的标题可以添加一个springdoc的配置类
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
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;
@Configuration
public class SpringDocConfig {
/**
* 一个自定义的 OpenAPI 对象
*
* @return 一个自定义的 OpenAPI 对象
*/
@Bean
public OpenAPI customOpenApi() {
return new OpenAPI()
//.components(new Components()
// 设置 spring security jwt accessToken 认证的请求头 Authorization: Bearer xxx.xxx.xxx
//.addSecuritySchemes("openApiSecurityScheme", new SecurityScheme()
// .type(SecurityScheme.Type.HTTP)
// .bearerFormat("JWT")
// .in(SecurityScheme.In.HEADER)
// .name("Authorization")
// .scheme("Bearer")))
// 设置标题、版本等信息
.info(new Info()
//设置标题
.title("Springdoc文档展示系统")
// 配置版本号
.version("0.0.1-SNAPSHOT")
// 配置文档描述
.description("SpringBoot3集成Swagger3示例文档")
// 配置作者信息
.contact(new Contact().name("菜鸟日记~").url("https://blog.csdn.net/qq_53900384?spm=1011.2415.3001.5343").email("xxx@xx.com"))
// 概述信息
.summary("Springdoc文档展示系统")
.termsOfService("")
// 配置License许可证信息
.license(new License()
.name("Apache 2.0")
.url("https://www.apache.org/licenses/LICENSE-2.0.html")));
}
}
配置后访问样例: