SpringBoot整合接口管理工具Swagger
一、Swagger簡(jiǎn)介
Swagger 是一系列 RESTful API 的工具，通過(guò) Swagger 可以獲得項(xiàng)目的?種交互式文檔，客戶端 SDK 的自動(dòng)生成等功能。
? Swagger 的目標(biāo)是為 REST APIs 定義一個(gè)標(biāo)準(zhǔn)的、與語(yǔ)?言無(wú)關(guān)的接口，使人和計(jì)算機(jī)在看不到源碼或者看不到文檔或者不能通過(guò)網(wǎng)絡(luò)流量檢測(cè)的情況下，能發(fā)現(xiàn)和理解各種服務(wù)的功能。當(dāng)服務(wù)通過(guò) Swagger 定義，消費(fèi)者就能與遠(yuǎn)程的服務(wù)互動(dòng)通過(guò)少量的實(shí)現(xiàn)邏輯。Swagger（絲襪哥）是世界上最流行的 API 表達(dá)工具。
二、Springboot整合swagger
?使用 Spring Boot 集成 Swagger 的理念是，使用用注解來(lái)標(biāo)記出需要在 API 文檔中展示的信息，Swagger 會(huì)根據(jù)項(xiàng)目中標(biāo)記的注解來(lái)生成對(duì)應(yīng)的 API 文檔。Swagger 被號(hào)稱(chēng)世界上最流行的 API 工具，它提供了 API 管理的全套解決方案，API 文檔管理需要考慮的因素基本都包含，這里將講解最常用的定制內(nèi)容。
1、添加swagger坐標(biāo)
Spring Boot 集成 Swagger 3 很簡(jiǎn)單，需要引入依賴并做基礎(chǔ)配置即可。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2、Swagger Helloword 實(shí)現(xiàn)
2.1、創(chuàng)建springboot項(xiàng)目
在啟動(dòng)類(lèi)上加上@EnableOpenApi 注解 啟用swagger api文檔功能
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;
@SpringBootApplication
@EnableOpenApi //啟動(dòng)swagger api文檔注解
public class SpringBootWithSwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SpringBootWithSwaggerApplication.class, args);
}
}
2.2、寫(xiě)一個(gè)接口
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @author 阿水
* @create 2023-04-11 9:54
*/
@RestController()
public class SwaggerController {
@GetMapping ("hello")
public String hello(String params) {
return "hello swagger"+" param為:"+params;
}
}
2.3、訪問(wèn)地址
http://localhost:8080/swagger-ui/index.html
三、常用的配置注解
? Swagger 通過(guò)注解表明該接口會(huì)生成文檔，包括接口名、請(qǐng)求方法、參數(shù)、返回信息等
1、Api 注解和 ApiOperation 注解
- @Api
使用在類(lèi)上，表明是swagger資源，@API擁有兩個(gè)屬性:value、tags。
生成的api文檔會(huì)根據(jù)tags分類(lèi)，直白的說(shuō)就是這個(gè)controller中的所有接口生成的接口文檔都會(huì)在tags這個(gè)list下；tags如果有多個(gè)值，會(huì)生成多個(gè)list，每個(gè)list都顯示所有接口
value的作用類(lèi)似tags,但是不能有多個(gè)值
語(yǔ)法:
@Api(tags = "用戶操作")
或
@Api(tags = {"用戶操作","用戶操作2"})
- @ApiOperation
使用于在方法上，表示一個(gè)http請(qǐng)求的操作
語(yǔ)法:
@ApiOperation(value = "",
notes = "",
response = )
屬性說(shuō)明：
value：方法說(shuō)明標(biāo)題
notes：方法詳細(xì)描述
response：方法返回值類(lèi)型
案例：使用@Api和@ApiOperation生成api文檔
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @author 阿水
* @create 2023-04-11 9:54
*/
@RestController()
@Api(tags = {"操作用戶"})
public class SwaggerController {
@GetMapping ("hello")
@ApiOperation(value = "swagger請(qǐng)求",notes = "阿水的第一個(gè)swagger請(qǐng)求",response = String.class)
public String hello(String params) {
return "hello swagger"+" param為:"+params;
}
}
2、ApiImplicitParams 注解和 ApiImplicitParam
@ApiImplicitParams 注解和 @ApiImplicitParam 用于對(duì)方法中的非對(duì)象參數(shù)(參數(shù)綁定到簡(jiǎn)單類(lèi)型時(shí)使用。)進(jìn)行說(shuō)明
語(yǔ)法:
@ApiImplicitParams(value = {
@ApiImplicitParam(name="", value = "", type = "", required = true, paramType = "", defaultValue = "")
})
屬性說(shuō)明：
name:形參名稱(chēng)
value:形參的說(shuō)明文字
type:形參類(lèi)型
required:該參數(shù)是否必須 true|false
paramType: 用于描述參數(shù)是以何種方式傳遞到 Controller 的，它的值常見(jiàn)有： path, query, body 和 header
path 表示參數(shù)是『嵌在』路徑中的，它和 @PathVariable 參數(shù)注解遙相呼應(yīng)；
query 表示參數(shù)是以 query string 的形式傳遞到后臺(tái)的（無(wú)論是 get 請(qǐng)求攜帶在 url 中，還是 post 請(qǐng)求攜帶在請(qǐng)求體中），它和 @RequestParam 參數(shù)注解遙相呼應(yīng)；
header 表示參數(shù)是『藏在』請(qǐng)求頭中傳遞到后臺(tái)的，它和 @RequestHeader 參數(shù)注解遙相呼應(yīng)的。
form 不常用.
defaultValue :參數(shù)默認(rèn)值
注意：@ApiImplicitParam 的 name 屬性要和 @RequestParam 或 @PathVariable 的 value 遙相呼應(yīng)。
案例：使用@ApiImplicitParams注解和 @ApiImplicitParam 對(duì)方法參數(shù)進(jìn)行說(shuō)明
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @author 阿水
* @create 2023-04-11 9:54
*/
@RestController()
@Api(tags = {"操作用戶"})
public class SwaggerController {
@GetMapping ("hello")
@ApiOperation(value = "swagger請(qǐng)求",notes = "阿水的第一個(gè)swagger請(qǐng)求",response = String.class)
@ApiImplicitParams(value ={
@ApiImplicitParam(name="param1",
value = "參數(shù)名1",
type = "String",
required = true,
paramType = "query",
defaultValue = "阿水所想的默認(rèn)值1" ),
@ApiImplicitParam(name="param2",
value = "參數(shù)名2",
type = "String",
required = true,
paramType = "query",
defaultValue = "阿水所想的默認(rèn)值2" )
})
public String hello(String param1,String param2) {
return "hello swagger"+" param1為:"+param1+"param2為"+param2;
}
}
3、ApiModel注解和 ApiModelProperty
@ApiModel
用在實(shí)體類(lèi)上，表示對(duì)類(lèi)進(jìn)行說(shuō)明，用于實(shí)體類(lèi)中的參數(shù)接收說(shuō)明。
@ApiModel("用戶類(lèi)")
@Data
public class Users {
@ApiModelProperty(value = "編碼：主鍵")
private Integer id;
@ApiModelProperty(value = "用戶名")
private String username;
@ApiModelProperty(value = "密碼")
private String password;
}
4、ApiResponse 和 ApiResponses
@ApiResponses 注解和 @ApiResponse 標(biāo)注在 Controller 的方法上，用來(lái)描述 HTTP 請(qǐng)求的響應(yīng)
/**
* 添加用戶
*
* @param user
* @return
*/
@PostMapping("/add")
@ApiOperation(value = "添加用戶",notes = "添加用戶信息",response = ResponseResult.class)
@ApiResponses({ @ApiResponse(code = 200, message = "添加成功", response = ResponseResult.class),
@ApiResponse(code = 500, message = "添加失敗", response = ResponseResult.class) })
public ResponseResult<Void> addUser(@RequestBody User user) {
//獲得生成的加密鹽
user.setSalt(SaltUtils.getSalt());
int n = userService.addUser(user);
if (n > 0) {
return new ResponseResult<Void>(200, "添加成功");
}
return new ResponseResult<Void>(500, "添加失敗");
}
5、創(chuàng)建 SwaggerConfig 配置類(lèi)
在 SwaggerConfig 中添加兩個(gè)方法：（其中一個(gè)方法是為另一個(gè)方法作輔助的準(zhǔn)備工作）
api()方法使用 @Bean，在啟動(dòng)時(shí)初始化，返回實(shí)例 Docket（Swagger API 摘要對(duì)象），這里需要注意的是 .apis(RequestHandlerSelectors.basePackage("xxx.yyy.zzz")) 指定需要掃描的包路路徑，只有此路徑下的 Controller 類(lèi)才會(huì)自動(dòng)生成 Swagger API 文檔。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* Swagger配置類(lèi)
*/
@Configuration //項(xiàng)目啟動(dòng)時(shí)加載此類(lèi)
public class SwaggerConfig {
@Bean
public Docket api(){
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
// 此處自行修改為自己的 Controller 包路徑。
.apis(RequestHandlerSelectors.basePackage("com.lps.controller"))
.paths(PathSelectors.any())
.build();
}
public ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("阿水的項(xiàng)目接口文擋")
.description("阿水的 Project Swagger2 UserService Interface") //說(shuō)明信息
.termsOfServiceUrl("http://localhost:8080/swagger-ui/index.html") //文檔生成的主頁(yè)地址
.version("1.0") //文檔版本
.build();
}
}
apiInfo()方法配置相對(duì)重要一些，主要配置頁(yè)面展示的基本信息包括，標(biāo)題、描述、版本、服務(wù)條款等，查看 ApiInfo 類(lèi)的源碼還會(huì)發(fā)現(xiàn)支持 license 等更多的配置
四、springsecurity整合swagger
4.1，配置放行的地址
http.authorizeRequests().antMatchers( "/swagger-ui.html",
"/swagger-ui/*",
"/swagger-resources/**",
"/v2/api-docs",
"/v3/api-docs",
"/webjars/**").permitAll()
.anyRequest().authenticated();
4.2，替換UI
上面的整個(gè)過(guò)程已經(jīng)完成了，但是生成的接口文檔的頁(yè)面，其實(shí)很多人不太喜歡，覺(jué)得不太符合國(guó)人的使用習(xí)慣，所有又有一些大神，提供了其他的UI測(cè)試頁(yè)面。這個(gè)頁(yè)面的使用還是比較廣泛的。
導(dǎo)入以下依賴、重啟工程后訪問(wèn)地址：http://localhost:8080/doc.html
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
到此這篇關(guān)于SpringBoot整合接口管理工具Swagger的文章就介紹到這了,更多相關(guān)SpringBoot整合Swagger內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
java基于C/S結(jié)構(gòu)實(shí)現(xiàn)多線程聊天室
這篇文章主要為大家詳細(xì)介紹了java基于C/S結(jié)構(gòu)實(shí)現(xiàn)多線程聊天室，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2019-01-01
本文我們將學(xué)習(xí)了解到用于Java的高性能緩存庫(kù)Caffeine,其使用Window TinyLfu清理策略,提供最佳的命中率2021-08-08
這篇文章主要介紹了Java 反射機(jī)制實(shí)例詳解的相關(guān)資料,這里對(duì)java中反射機(jī)制進(jìn)行了詳細(xì)的分析，需要的朋友可以參考下2017-09-09
Spring Data JPA中的動(dòng)態(tài)查詢實(shí)例
本篇文章主要介紹了詳解Spring Data JPA中的動(dòng)態(tài)查詢。小編覺(jué)得挺不錯(cuò)的，現(xiàn)在分享給大家，也給大家做個(gè)參考。一起跟隨小編過(guò)來(lái)看看吧2017-04-04
這篇文章主要介紹了Spring Boot與React集成的示例代碼，小編覺(jué)得挺不錯(cuò)的，現(xiàn)在分享給大家，也給大家做個(gè)參考。一起跟隨小編過(guò)來(lái)看看吧2018-11-11
基于Java實(shí)現(xiàn)簡(jiǎn)單的身材計(jì)算程序
這篇文章主要為大家詳細(xì)介紹了如何利用Java實(shí)現(xiàn)簡(jiǎn)單的身材計(jì)算程序，可以計(jì)算身體的體脂率以及BMI數(shù)值等，感興趣的小伙伴可以跟隨小編一起學(xué)習(xí)一下2022-12-12
Springboot Vue可配置調(diào)度任務(wù)實(shí)現(xiàn)示例詳解
這篇文章主要為大家介紹了Springboot Vue可配置調(diào)度任務(wù)實(shí)現(xiàn)示例詳解，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進(jìn)步，早日升職加薪2023-01-01![Java List集合返回值去掉中括號(hào)(''[ ]'')的操作](http://img.jbzj.com/images/xgimg/bcimg7.png)
Java List集合返回值去掉中括號(hào)(''[ ]'')的操作
這篇文章主要介紹了Java List集合返回值去掉中括號(hào)('[ ]')的操作，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。一起跟隨小編過(guò)來(lái)看看吧2020-08-08
詳解springMVC之與json數(shù)據(jù)交互方法
本篇文章主要介紹了詳解springMVC之與json數(shù)據(jù)交互方法，小編覺(jué)得挺不錯(cuò)的，現(xiàn)在分享給大家，也給大家做個(gè)參考。一起跟隨小編過(guò)來(lái)看看吧2017-05-05
淺析SpringBoot中使用thymeleaf找不到.HTML文件的原因
這篇文章主要介紹了SpringBoot中使用thymeleaf找不到.HTML文件的原因分析，本文給大家介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值，需要的朋友可以參考下2020-07-07