Spring Boot 3.x 引入springdoc-openapi (内置Swagger UI、webmvc-api)
憨憨憨羊 2024-08-19 14:33:05 阅读 75
接触的原因
因开发自己的项目时,写接口文档很繁琐,查到后端都在用swagger等接口工具来记录接口文档,于是学习了一下,本文记录个人配置过程,有问题欢迎指正交流😁
Swagger: Swagger是一种Rest API的表示方式,它是标准的、语言无关的工具,这种表示方式不仅人可读,而且机器也可读。Swagger提供了一套完整的规范来描述API接口,包括请求和响应的数据模型、操作行为等。它通过注解或配置文件的方式与代码集成,以生成API文档。
SpringDoc: SpringDoc是基于OpenAPI 3规范的,专为Spring Boot设计的API文档生成工具。它提供了与Spring Boot更好的集成,支持Spring Boot全系列。SpringDoc利用JSR-303中的注解(如@NotNull、@Min、@Max、@Size等)来描述API的参数验证信息。此外,SpringDoc的接口信息可以通过JSON展示,也可以与Swagger-ui集成,提供可视化的API文档界面。
在网上看了许多教程,发现很多都是针对Spring Boot 2 框架的,即使有针对Spring Boot 3 的,用法也不太一样,经过对比测试,最后我使用的是 SpringDoc OpenAPI Starter WebMvc UI
它是 Spring Boot 项目中用于自动生成 API 文档的一个依赖库。它结合了 Swagger UI,提供了一个可视化的界面来展示和测试你的 RESTful APIs。这个依赖库特别适用于使用 Spring Web MVC 框架构建的项目。
这个依赖项包括了 Swagger UI 和 SpringDoc OpenAPI Starter WebMvc API,无需额外引入其他依赖即可使用。
pom.xml 配置
我的 spring boot 版本是 3.1.8
引入 springdoc 依赖(记得点击右上角的带蓝色的M按钮进行依赖下载)
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.1.8</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<dependencies>
<!-- 其他依赖 -->
<!-- 加入 springdoc 依赖 -->
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.5.0</version>
</dependency>
</dependencies>
可以在pom.xml 文件引入阿里云镜像 (与 dependencies 同级!!)
<repositories>
<!--阿里云镜像-->
<repository>
<id>alimaven</id>
<name>aliyun maven</name>
<url>https://maven.aliyun.com/nexus/content/groups/public/</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
application.yml 配置
server:
port: 5000
springdoc:
api-docs:
enabled: true # 开启OpenApi接口
path: /v3/api-docs # 自定义路径,默认为 "/v3/api-docs"
swagger-ui:
enabled: true # 开启swagger界面,依赖OpenApi,需要OpenApi同时开启
path: /swagger-ui/index.html # 自定义路径,默认为"/swagger-ui/index.html"
如果需要更改这里的路径,切记在拦截器配置那里对应更改,后面会贴配置,但是只针对我上面这个路径,根据自己的需求改一下。
SwaggerConfig.java 配置
// 你自己的包名
package com.xxx.xxx.config;
import io.swagger.v3.oas.models.ExternalDocumentation;
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 org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* @Author HHHY
* @ClassName
* @Date: 2024/4/2 14:21
* @Description: Swagger 配置
*/
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(new Info().title("Spring Boot 中使用 Swagger UI 构建 RESTful API")
.contact(new Contact())
.description("百草中医药信息管理平台提供的 RESTful API")
.version("v1.0.0")
.license(new License().name("Apache 2.0").url("http://springdoc.org")))
.externalDocs(new ExternalDocumentation()
.description("外部文档")
.url("https://springshop.wiki.github.org/docs"));
}
}
若你没有设置拦截器,那么到这里直接访问 http://localhost:5000/swagger-ui/swagger-ui/index.html#/
应该就可以跑起来了,其中 localhost:端口号
是你自己在 application
里设置的。
但是 ?!!
当我满心欢喜的准备迎接属于自己的接口文档时,
蒙住了,已经搞了几个小时了…于是我遍览各位大佬的帖子,终于让我找到了蛛丝马迹,感谢这位大佬这篇文章的最后那段话给我的启发,指路——Spring Boot引入swagger-ui 后swagger-ui.html无法访问404于是我想起来自己昨天弄了一个拦截器,长这样:
<code>package com.ykl.springboot_tcmi.config;
import com.ykl.springboot_tcmi.interceptors.LoginInterceptor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* @Author HHHY
* @ClassName
* @Date: 2024/4/1 23:16
* @Description: 配置类 注册拦截器
*/
@Configuration
public class WebConfig implements WebMvcConfigurer {
// 注入拦截器对象
@Autowired
private LoginInterceptor loginInterceptor;
@Override
public void addInterceptors(InterceptorRegistry registry) {
// 部分接口不拦截
registry.addInterceptor(loginInterceptor)
.excludePathPatterns("/api/users/login", "/api/users/register", "/api/rights?flag=front");
}
}
若你发现和我一样都不能访问 json 与 ui 界面,那么在上述配置都正确的情况下,可能是你的拦截器出了问题,我是这么配置的:
// 前面都不变
@Override
public void addInterceptors(InterceptorRegistry registry) {
// 部分接口不拦截
registry.addInterceptor(loginInterceptor)
.excludePathPatterns("/api/users/login", "/api/users/register", "/api/rights?flag=front")
// 【看这里!!!】根据你自己的路径加上这个配置
.excludePathPatterns("/swagger-ui/**", "/v3/api-docs/**");
}
配置完拦截器的东西,应该就可以正常访问了!
我看到说还要配置什么静态资源访问,目前还没写到这方面内容,我也不太懂,既然能跑起来,就没加上,能跑就行,能跑就行…
前端同学开心的去写接口了(bushi😅)
注意
我一开始写的路径是这样的 <code>"/swagger-ui/index.html", "/v3/api-docs" ,然后发现可以访问到 json的数据,但是无法访问 ui 界面,又是百思不得其解,然后虽然很蠢但是真没想到是不能加上具体的index.html
,但是在看别人代码的时候灵光一闪,试着改成了"/swagger-ui/**"
,结果能成了,但是…
是的我又傻眼了 ,因为网上版本真的很多…试了很多都不行…好不容易到这了…,也不差这会儿,容我再琢磨一波…作为一个未来合格的前端从业者(手动滑稽),我熟练的打开了 F12
果然,被我找到了吧哈哈哈哈
这里不仅只有<code>"/v3/api-docs"发送的请求,所以"/v3/api-docs/**"
搞定!!
具体使用这里就不说了,因为我也是才接触,仅仅了解就不班门弄斧了,感兴趣的同学可以去看看springdoc-openapi官网或者大佬们的文章或视频学习一下😊
上一篇: 【Vue3】解锁Vue3黑科技:探索接口、泛型和自定义类型的前端奇迹
下一篇: 微信小程序完整项目实战(前端+后端)
本文标签
Spring Boot 3.x 引入springdoc-openapi (内置Swagger UI、webmvc-api)
声明
本文内容仅代表作者观点,或转载于其他网站,本站不以此文作为商业用途
如有涉及侵权,请联系本站进行删除
转载本站原创文章,请注明来源及作者。