Springboot整合Swagger3全注解配置(springdoc-openapi-ui)
一、創(chuàng)建Springboot項(xiàng)目,引入pom依賴
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>1.18.12</version> </dependency> <!-- 只需要引入這一個(gè)依賴就行了 --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.5.5</version> </dependency>
二、配置類(lèi)請(qǐng)求頭攜帶token
import io.swagger.v3.oas.annotations.ExternalDocumentation; import io.swagger.v3.oas.annotations.OpenAPIDefinition; import io.swagger.v3.oas.annotations.enums.SecuritySchemeIn; import io.swagger.v3.oas.annotations.enums.SecuritySchemeType; import io.swagger.v3.oas.annotations.info.Contact; import io.swagger.v3.oas.annotations.info.Info; import io.swagger.v3.oas.annotations.security.SecurityRequirement; import io.swagger.v3.oas.annotations.security.SecurityScheme; @OpenAPIDefinition( info = @Info( title = "Swagger3", version = "1.0", description = "Swagger3使用演示", contact = @Contact(name = "TOM") ), security = @SecurityRequirement(name = "JWT"), externalDocs = @ExternalDocumentation(description = "參考文檔", url = "https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations" ) ) @SecurityScheme(type = SecuritySchemeType.HTTP, name = "JWT", scheme = "bearer", in = SecuritySchemeIn.HEADER) public class Swagger3Config { }
- @OpenAPIDefinition全局只能定義一個(gè),主要配置文檔信息和安全配置,這里列舉了常用的請(qǐng)求頭攜帶token的安全配置模式
- @OpenAPIDefinition下的info屬性配置文檔信息
- @OpenAPIDefinition下的security配置認(rèn)證方式,name屬性引入自定義的認(rèn)證模式
- @SecurityScheme注解就是自定義的認(rèn)證模式,配置請(qǐng)求頭攜帶token
三、配置文件
server: port: 8080 springdoc: api-docs: #是否開(kāi)啟文檔功能 enabled: true #swagger后端請(qǐng)求地址 path: /api-docs swagger-ui: #自定義swagger前端請(qǐng)求路徑,輸入http:127.0.0.1:8080/test會(huì)自動(dòng)重定向到swagger頁(yè)面 path: /test #包掃描路徑 packages-to-scan: com.hello.controller,com.hello.dto #這里定義了兩個(gè)分組,可定義多個(gè),也可以不定義 group-configs: #分組名 - group: admin #按路徑匹配 pathsToMatch: /admin/** #分組名 - group: user #按包路徑匹配 packagesToScan: com.hello.api.user
四、接口定義
定義兩個(gè)接口
package com.hello.api.admin; import com.hello.dto.CommonResult; import com.hello.dto.User; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.media.Schema; import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.tags.Tag; @Tag(name = "AdminControllerApi", description = "管理員相關(guān)接口") public interface AdminControllerApi { @Operation(summary = "管理員添加用戶", description = "根據(jù)姓名添加用戶并返回", parameters = { @Parameter(name = "name", description = "姓名") }, responses = { @ApiResponse(description = "返回添加的用戶", content = @Content(mediaType = "application/json", schema = @Schema(anyOf = {CommonResult.class, User.class}))), @ApiResponse(responseCode = "400", description = "返回400時(shí)候錯(cuò)誤的原因") } ) CommonResult<User> addUser(String name); @Operation(summary = "管理員刪除用戶", description = "根據(jù)姓名刪除用戶") @ApiResponse(description = "返回添加的用戶", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))) CommonResult<User> delUser(@Parameter(description = "姓名") String name); @Operation(summary = "管理員更新用戶", description = "管理員根據(jù)姓名更新用戶") @ApiResponse(description = "返回更新的用戶", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))) CommonResult<User> updateUser(@Parameter(schema = @Schema(implementation = User.class), required = true, description = "用戶類(lèi)") User user); }
package com.hello.api.user; import com.hello.dto.User; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.media.Schema; import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.tags.Tag; @Tag(name = "UserControllerApi", description = "用戶的增刪改查") public interface UserControllerApi { @Operation(summary = "添加用戶", description = "根據(jù)姓名添加用戶并返回", parameters = { @Parameter(name = "name", description = "姓名") }, responses = { @ApiResponse(description = "返回添加的用戶", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))), @ApiResponse(responseCode = "400", description = "返回400時(shí)候錯(cuò)誤的原因")} ) User addUser(String name); @Operation(summary = "刪除用戶", description = "根據(jù)姓名刪除用戶", parameters = { @Parameter(name = "name", description = "姓名") }) void delUser(String name); }
五、實(shí)現(xiàn)類(lèi)
實(shí)現(xiàn)剛才的兩個(gè)接口
package com.hello.controller.admin; import com.hello.api.admin.AdminControllerApi; import com.hello.dto.CommonResult; import com.hello.dto.User; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/admin") @Slf4j public class AdminController implements AdminControllerApi { @PostMapping("/add/{name}") @Override public CommonResult<User> addUser(@PathVariable String name) { return CommonResult.success(new User(name, 18)); } @GetMapping("/del/{name}") @Override public CommonResult<User> delUser(@PathVariable String name) { log.info("管理員刪除name={}的用戶", name); return CommonResult.success(new User(name, 25)); } @PostMapping("/update") @Override public CommonResult<User> updateUser(@RequestBody User user) { user.setAge(100); log.info("管理員更新{}用戶的年齡為{}", user, 100); return CommonResult.success(user); } }
package com.hello.controller.user; import com.hello.api.user.UserControllerApi; import com.hello.dto.User; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/user") @Slf4j public class UserController implements UserControllerApi { @PostMapping("/add/{name}") @Override public User addUser(@PathVariable String name) { return new User(name, 18); } @GetMapping("/del/{name}") @Override public void delUser(@PathVariable String name) { log.info("刪除name={}的用戶", name); } }
六、實(shí)體類(lèi)定義
package com.hello.dto; import io.swagger.v3.oas.annotations.media.Schema; import lombok.AllArgsConstructor; import lombok.Getter; import lombok.Setter; @Getter @Setter @AllArgsConstructor @Schema(name = "CommonResult", description = "通用返回對(duì)象") public class CommonResult<T> { @Schema(name = "code", description = "狀態(tài)碼") private long code; @Schema(name = "message", description = "提示信息") private String message; @Schema(name = "data", description = "數(shù)據(jù)封裝") private T data; /** * 成功返回結(jié)果 * * @param data 獲取的數(shù)據(jù) */ public static <T> CommonResult<T> success(T data) { return new CommonResult<T>(200, "操作成功", data); } /** * 失敗返回結(jié)果 * * @param message 提示信息 */ public static <T> CommonResult<T> failed(String message) { return new CommonResult<T>(400, message, null); } }
package com.hello.dto; import io.swagger.v3.oas.annotations.media.Schema; import lombok.AllArgsConstructor; import lombok.Data; @Schema(name="User",description ="用戶信息" ) @Data @AllArgsConstructor public class User { @Schema(name = "name",description = "姓名") private String name; @Schema(name = "age",description = "年齡") private int age; }
七、運(yùn)行項(xiàng)目查看效果
瀏覽器輸入127.0.0.1:8080/test會(huì)重定向到swagger頁(yè)面
點(diǎn)擊右上角的Authorize就會(huì)彈出以下界面,輸入token,請(qǐng)求接口就會(huì)自動(dòng)攜帶該token發(fā)送請(qǐng)求,這里隨便輸入一個(gè)abc為token,點(diǎn)擊Authorize
打開(kāi)一個(gè)接口去測(cè)試,查看效果,發(fā)現(xiàn)請(qǐng)求已經(jīng)自動(dòng)攜帶了token
到此這篇關(guān)于Springboot整合Swagger3全注解配置(springdoc-openapi-ui)的文章就介紹到這了,更多相關(guān)Springboot Swagger3全注解配置內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!
相關(guān)文章
數(shù)組重排序(如何將所有奇數(shù)都放在所有偶數(shù)前面)的深入分析
本篇文章是對(duì)數(shù)組重排序(如何將所有奇數(shù)都放在所有偶數(shù)前面)的方法進(jìn)行了詳細(xì)的分析介紹,需要的朋友參考下2013-06-06Java服務(wù)端如何解決跨域問(wèn)題?CORS請(qǐng)求頭方式
這篇文章主要介紹了Java服務(wù)端如何解決跨域問(wèn)題?CORS請(qǐng)求頭方式,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2022-11-11Spring中@DependsOn注解的作用及實(shí)現(xiàn)原理解析
這篇文章主要介紹了Spring中@DependsOn注解的作用及實(shí)現(xiàn)原理解析,本文給大家介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值,需要的朋友可以參考下2021-03-03Java中的main方法調(diào)用非靜態(tài)方法處理
這篇文章主要介紹了Java中的main方法調(diào)用非靜態(tài)方法處理,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2023-06-06解決Maven 項(xiàng)目報(bào)錯(cuò) java.httpservlet和synchronized使用方法
下面小編就為大家?guī)?lái)一篇解決Maven 項(xiàng)目報(bào)錯(cuò) java.httpservlet和synchronized使用方法。小編覺(jué)得挺不錯(cuò)的,現(xiàn)在就分享給大家,也給大家做個(gè)參考。一起跟隨小編過(guò)來(lái)看看吧2017-07-07