接觸的原因
因開發(fā)自己的項目時，寫接口文檔很繁瑣，查到后端都在用swagger等接口工具來記錄接口文檔，于是學(xué)習(xí)了一下，本文記錄個人配置過程，有問題歡迎指正交流??
Swagger： Swagger是一種Rest API的表示方式，它是標準的、語言無關(guān)的工具，這種表示方式不僅人可讀，而且機器也可讀。Swagger提供了一套完整的規(guī)范來描述API接口，包括請求和響應(yīng)的數(shù)據(jù)模型、操作行為等。它通過注解或配置文件的方式與代碼集成，以生成API文檔。
SpringDoc： SpringDoc是基于OpenAPI 3規(guī)范的，專為Spring Boot設(shè)計的API文檔生成工具。它提供了與Spring Boot更好的集成，支持Spring Boot全系列。SpringDoc利用JSR-303中的注解（如@NotNull、@Min、@Max、@Size等）來描述API的參數(shù)驗證信息。此外，SpringDoc的接口信息可以通過JSON展示，也可以與Swagger-ui集成，提供可視化的API文檔界面。
在網(wǎng)上看了許多教程，發(fā)現(xiàn)很多都是針對Spring Boot 2 框架的，即使有針對Spring Boot 3 的，用法也不太一樣，經(jīng)過對比測試，最后我使用的是 SpringDoc OpenAPI Starter WebMvc UI
它是 Spring Boot 項目中用于自動生成 API 文檔的一個依賴庫。它結(jié)合了 Swagger UI，提供了一個可視化的界面來展示和測試你的 RESTful APIs。這個依賴庫特別適用于使用 Spring Web MVC 框架構(gòu)建的項目。
這個依賴項包括了 Swagger UI 和 SpringDoc OpenAPI Starter WebMvc API，無需額外引入其他依賴即可使用。
pom.xml 配置
我的 spring boot 版本是 3.1.8
引入 springdoc 依賴（記得點擊右上角的帶藍色的M按鈕進行依賴下載）
<parent>
<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 同級?。。?/strong>
<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"
如果需要更改這里的路徑，切記在攔截器配置那里對應(yīng)更改，后面會貼配置，但是只針對我上面這個路徑，根據(jù)自己的需求改一下。
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 構(gòu)建 RESTful API")
.contact(new Contact())
.description("百草中醫(yī)藥信息管理平臺提供的 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"));
}
}
若你沒有設(shè)置攔截器，那么到這里直接訪問 http://localhost:5000/swagger-ui/swagger-ui/index.html#/ 應(yīng)該就可以跑起來了，其中 localhost:端口號 是你自己在 application 里設(shè)置的。
但是 ???！
當我滿心歡喜的準備迎接屬于自己的接口文檔時，
蒙住了，已經(jīng)搞了幾個小時了…于是我遍覽各位大佬的帖子，終于讓我找到了蛛絲馬跡，感謝這位大佬這篇文章的最后那段話給我的啟發(fā)，指路——Spring Boot引入swagger-ui 后swagger-ui.html無法訪問404于是我想起來自己昨天弄了一個攔截器，長這樣：
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");
}
}
若你發(fā)現(xiàn)和我一樣都不能訪問 json 與 ui 界面，那么在上述配置都正確的情況下，可能是你的攔截器出了問題，我是這么配置的：
// 前面都不變
@Override
public void addInterceptors(InterceptorRegistry registry) {
// 部分接口不攔截
registry.addInterceptor(loginInterceptor)
.excludePathPatterns("/api/users/login", "/api/users/register", "/api/rights?flag=front")
// 【看這里?。。 扛鶕?jù)你自己的路徑加上這個配置
.excludePathPatterns("/swagger-ui/**", "/v3/api-docs/**");
}
配置完攔截器的東西，應(yīng)該就可以正常訪問了！
我看到說還要配置什么靜態(tài)資源訪問，目前還沒寫到這方面內(nèi)容，我也不太懂，既然能跑起來，就沒加上，能跑就行，能跑就行…
前端同學(xué)開心的去寫接口了（bushi??） 
注意
我一開始寫的路徑是這樣的 "/swagger-ui/index.html", "/v3/api-docs" ，然后發(fā)現(xiàn)可以訪問到 json的數(shù)據(jù)，但是無法訪問 ui 界面，又是百思不得其解，然后雖然很蠢但是真沒想到是不能加上具體的index.html，但是在看別人代碼的時候靈光一閃，試著改成了"/swagger-ui/**"，結(jié)果能成了，但是…
文章來源：http://www.zghlxwxcb.cn/news/detail-859967.html
是的我又傻眼了 ,因為網(wǎng)上版本真的很多…試了很多都不行…好不容易到這了…，也不差這會兒，容我再琢磨一波…作為一個未來合格的前端從業(yè)者(手動滑稽)，我熟練的打開了 F12
果然，被我找到了吧哈哈哈哈
這里不僅只有"/v3/api-docs"發(fā)送的請求，所以"/v3/api-docs/**" 搞定?。?br>
具體使用這里就不說了，因為我也是才接觸，僅僅了解就不班門弄斧了，感興趣的同學(xué)可以去看看springdoc-openapi官網(wǎng)或者大佬們的文章或視頻學(xué)習(xí)一下??文章來源地址http://www.zghlxwxcb.cn/news/detail-859967.html
到了這里，關(guān)于Spring Boot 3.x 引入springdoc-openapi (內(nèi)置Swagger UI、webmvc-api)的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
