1.本地工作環(huán)境
ide2021
jdk17
springboot3.0.11-SNAPSHOT
2.使用knife4j-openapi3的原因
在使用springboot3寫完一個(gè)項(xiàng)目后，想快速生成一篇接口文檔，供自己觀看。在網(wǎng)上沖浪一段時(shí)間后，發(fā)現(xiàn)使用Swagger文檔比較合適，通過(guò)少量的注解來(lái)完成一篇復(fù)雜的文檔。說(shuō)干就干，直接cope網(wǎng)上的資料寫一個(gè)demo來(lái)用，發(fā)現(xiàn)項(xiàng)目無(wú)法正常啟動(dòng)。在翻閱了博客后，發(fā)現(xiàn)Swagger2暫時(shí)無(wú)法適配springboot3。后再其他博客中發(fā)現(xiàn)可以使用openapi兼容springboot3,同時(shí)，knife4j是對(duì)swagger的美化，所以使用knife4j-openapi3。
3.進(jìn)行配置
對(duì)應(yīng)的依賴如下:
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.1.0</version>
</dependency>配置文件采用yml格式，所以在配置中對(duì)knife4j進(jìn)行如下簡(jiǎn)單配置
# 在線文檔配置
springdoc:
swagger-ui:
# 配置swagger-ui界面訪問(wèn)路徑
path: /swagger-ui.html
# 包掃描路徑
packages-to-scan: com.pjx.sys.controller
# 默認(rèn)開(kāi)啟wend
api-docs:
enabled: true上述的 packages-to-scan 也就是包掃描路徑，是對(duì)控制層進(jìn)行掃描，也就是你的controller層，只要掃描到外面那一層，不要深入到內(nèi)部。路徑可以直接復(fù)制。
此時(shí)還需對(duì)knife4j進(jìn)行配置，才可以使用。
在自己的項(xiàng)目中創(chuàng)建SwaggerConfig類進(jìn)行配置
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;
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(new Info().title("標(biāo)題")
//描敘
.description("我的API文檔")
//版本
.version("v1")
//作者信息，自行設(shè)置
.contact(new Contact().name("彭").email("11111").url("https://www.baidu.com"))
//設(shè)置接口文檔的許可證信息
.license(new License().name("Apache 2.0").url("http://springdoc.org")));
}
}在這里基本的配置算是完成了，接下來(lái)用一個(gè)簡(jiǎn)單的demo演示
上面是對(duì)應(yīng)的結(jié)構(gòu)，下面分別為控制層和pojo
import com.example.test.pojo.Books;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@Tag(name = "測(cè)試",description = "描述")
@RestController
@RequestMapping("/getBooks")
public class BookController {
@GetMapping
@Operation(summary = "測(cè)試接口")
public Books getBooks(){
Books books = new Books();
books.setId(1);
return books;
}
}
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
@Schema
@Data
public class Books {
@Schema(name = "id",description = "用戶id",defaultValue = "12",example = "1")
private Integer id;
}以上完成后，一個(gè)簡(jiǎn)單的文檔就完成了，直接看效果。
doc.html
swagger-ui
在demo完成，發(fā)現(xiàn)沒(méi)有問(wèn)題后，便開(kāi)始在自己的項(xiàng)目中導(dǎo)入配置，然后出現(xiàn)一系列問(wèn)題。
4.自己的項(xiàng)目中出現(xiàn)的問(wèn)題
4.1可以訪問(wèn)swagger -ui但是無(wú)法訪問(wèn)doc.html
當(dāng)時(shí)我也不知道怎么回事，在想，為什么不可以顯示？為什么swagger-ui可以使用？為什么demo可以使用?程序員的三連懵逼。。。最后在瀏覽了大量的博客后，發(fā)現(xiàn)是自己腦子抽了。
首先，要知道，這些資源在哪里，他們?cè)趉nife4j的jar包中,包你雖然導(dǎo)入了，但是資源你不告訴spring boot，這讓它怎么找？找空氣嗎？其次，swagger-ui可以可以使用，是因?yàn)樵趛ml文件中配置了，doc沒(méi)有配置，也沒(méi)有配置方法，demo可以使用，而項(xiàng)目中的不可以使用，是因?yàn)閟pringboot版本太高，有時(shí)找不到資源，需要你手動(dòng)告訴它，也就回到問(wèn)題1了。
對(duì)應(yīng)的資源如下：
4.1.1解決方法
在WebConfig配置類中實(shí)現(xiàn)WebMvcConfigurer接口，重寫addResourceHandlers方法,導(dǎo)入資源的位置。
@Component
public class WebConfig implements WebMvcConfigurer {
/**
* 靜態(tài)資源映射
*
* @param registry
*/
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}如此，資源便讓springboot找到了，當(dāng)然，如果配置了攔截器，則需要忽略一些資源,可以在WebMvcConfigurer接口中實(shí)現(xiàn)addInterceptors方法，在內(nèi)部用addInterceptor定義自己的攔截器，用addPathPatterns添加攔截路徑和excludePatterns添加忽略路徑，我的忽略路徑如下
"/v3/api-docs/**", "/doc.html", "/webjars/**", "/swagger-resources", "/swagger-ui/**"若不知道要忽略的具體資源，可以直接在瀏覽器的? ?網(wǎng)絡(luò)? 中，采用Shift+f5的方式，哪些請(qǐng)求報(bào)錯(cuò)，就忽略哪些資源。這樣，doc.html便可以訪問(wèn)了。
4.2關(guān)于在doc.html找不到圖標(biāo)的問(wèn)題
這個(gè)問(wèn)題說(shuō)大嘛也不大，但是看著瀏覽器報(bào)錯(cuò)也不是很喜歡，在網(wǎng)上查閱了資料后，發(fā)現(xiàn)可能是圖標(biāo)侵權(quán)了，然后后面不讓用了。
4.2.1解決方法
自行在靜態(tài)資源文件夾下放一張favicon.ico的圖片，喜歡什么就放什么，但是后綴名要相同。一定要ico的文件。從網(wǎng)上下載一張喜歡的，后綴名自己改好。
放入后，并沒(méi)有萬(wàn)事大吉了，還要讓spring boot知道這個(gè)圖標(biāo)，不然還是無(wú)法訪問(wèn)，同樣需要添加靜態(tài)資源映射。在4.1.1方法里面添加
registry.addResourceHandler("favicon.ico").addResourceLocations("classpath:/static/");同時(shí)在忽略路徑里面添加 /favicon.ico, 也就是放行這張圖，讓瀏覽器可以找到。
最后解決完成。撒花。
開(kāi)玩笑啦。
5.在實(shí)體類和控制層的簡(jiǎn)單運(yùn)用。
5.1實(shí)體類
直接上代碼，好吧。
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
@Schema
@Data
public class User {
//id
@Schema(name = "id",description = "序列號(hào)",defaultValue = "1",example = "1")
private Integer id;
//用戶名
@Schema(name = "username",description = "用戶名",defaultValue = "not null",example = "admin")
private String username;
//密碼
@Schema(name = "password",description = "密碼",defaultValue = "not null",example = "******")
private String password;
//權(quán)限id
@Schema(name = "roleId",description = "權(quán)限id,判斷是否擁有此權(quán)限",defaultValue = "not null",example = "admin")
private Integer roleId;
//是否默認(rèn)
@Schema(name = "is_default",description = "0為默認(rèn)用戶,1為普通用戶",defaultValue = "1",example = "1")
private Integer is_default;
//權(quán)限
@Schema(hidden = true)
private Role role;
//token
@Schema(name = "token",description = "存儲(chǔ)前端的token",defaultValue = "not null",example = "dsafasdff341234123...")
private String token;
}
@Schema注解用于描述類的屬性，description為描敘，defaultValue為默認(rèn)值，example為舉例子，hidden為忽略。
5.2控制層
import com.pjx.sys.service.UploadService;
import com.pjx.sys.util.R;
import com.pjx.sys.util.SYSCode;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.annotation.Resource;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;
import java.io.FileNotFoundException;
@Tag(name = "上傳圖片")
@RestController
@RequestMapping("/adminapi/upload")
public class UploadController {
//導(dǎo)入U(xiǎn)ploadService
@Resource
private UploadService uploadService;
@Operation(method = "POST", summary = "更新背景圖", description = "通過(guò)傳入指定規(guī)格的圖片，更新實(shí)驗(yàn)室的背景圖")
@PostMapping
public R uploadBg(@Parameter(description = "圖片對(duì)象") @RequestParam("file") MultipartFile file) {
try {
uploadService.uploadBg(file);
return new R(SYSCode.CODE_SUCCESS, "上傳成功");
} catch (FileNotFoundException e) {
e.printStackTrace();
}
return new R(SYSCode.CODE_ERROR, "上傳失敗");
}
}
@Tag用于對(duì)API接口進(jìn)行標(biāo)記和分組。
@Operation用于對(duì)API接口方法進(jìn)行詳細(xì)的操作描述，method為方法，summary為簡(jiǎn)介，description為描敘。
@Parameter用于指定操作的參數(shù)列表。
其他的方法不全，暫時(shí)如下：
文章來(lái)源：http://www.zghlxwxcb.cn/news/detail-766694.html
文章來(lái)源地址http://www.zghlxwxcb.cn/news/detail-766694.html
到了這里，關(guān)于springboot3.0.11-SNAPSHOT使用knife4j-openapi3所遇見(jiàn)的問(wèn)題的文章就介紹完了。如果您還想了解更多內(nèi)容，請(qǐng)?jiān)谟疑辖撬阉鱐OY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
