Swagger 是一系列 RESTful API 的工具，透過 Swagger 可以獲得專案的⼀種互動式文檔，客戶端 SDK 的自動生成等功能。
Swagger 的目標是為REST APIs 定義一個標準的、與語⾔言無關的接口，使人和計算機在看不到源碼或者看不到文檔或者不能通過網絡流量檢測的情況下，能發現並理解各種服務的功能。當服務透過 Swagger 定義，消費者就能與遠端的服務互動透過少量的實現邏輯。
使用Spring Boot 整合Swagger 的理念是，使用註解來標記需要在API 文件中展示的訊息，Swagger 會根據專案中標記的註解來產生對應的API 文件。 Swagger 被號稱世界上最受歡迎的 API 工具，它提供了 API 管理的全套解決方案，API 文件管理需要考慮的因素基本上都包含，這裡將講解最常用的客製化內容。
Spring Boot 整合 Swagger 3 很簡單，需要引入依賴並做基礎配置即可。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>在啟動類別上加上@EnableOpenApi 註解啟用swagger api文件功能
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;
@SpringBootApplication
@EnableOpenApi //启动swagger api文档注解
public class SpringBootWithSwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SpringBootWithSwaggerApplication.class, args);
}
}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;
}
}
http://localhost:8080/swagger-ui/index.html
@Api
语法:
@Api(tags = "用户操作")
或
@Api(tags = {"用户操作","用户操作2"})语法:
@ApiOperation(value = "",
notes = "",
response = )
属性说明：
value：方法说明标题
notes：方法详细描述
response：方法返回值类型案例：使用@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请求",notes = "阿水的第一个swagger请求",response = String.class)
public String hello(String params) {
return "hello swagger"+" param为:"+params;
}
}2、
ApiImplicitParams 註解和 #@ApiImplicitParam用於對方法中的非物件綁定到簡單類型時使用。)進行說明语法:
@ApiImplicitParams(value = {
@ApiImplicitParam(name="", value = "", type = "", required = true, paramType = "", defaultValue = "")
})
属性说明：
name:形参名称
value:形参的说明文字
type:形参类型
required:该参数是否必须 true|false
paramType: 用于描述参数是以何种方式传递到 Controller 的，它的值常见有： path, query, body 和 header
path 表示参数是『嵌在』路径中的，它和 @PathVariable 参数注解遥相呼应；
query 表示参数是以 query string 的形式传递到后台的（无论是 get 请求携带在 url 中，还是 post 请求携带在请求体中），它和 @RequestParam 参数注解遥相呼应；
header 表示参数是『藏在』请求头中传递到后台的，它和 @RequestHeader 参数注解遥相呼应的。
form 不常用.
defaultValue :参数默认值
案例：使用@ApiImplicitParams註解和@ApiImplicitParam 對方法參數進行說明
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请求",notes = "阿水的第一个swagger请求",response = String.class)
@ApiImplicitParams(value ={
@ApiImplicitParam(name="param1",
value = "参数名1",
type = "String",
required = true,
paramType = "query",
defaultValue = "阿水所想的默认值1" ),
@ApiImplicitParam(name="param2",
value = "参数名2",
type = "String",
required = true,
paramType = "query",
defaultValue = "阿水所想的默认值2" )
})
public String hello(String param1,String param2) {
return "hello swagger"+" param1为:"+param1+"param2为"+param2;
}
}
3、ApiModel註解和ApiModelProperty
@ApiModel("用户类")
@Data
public class Users {
@ApiModelProperty(value = "编码：主键")
private Integer id;
@ApiModelProperty(value = "用户名")
private String username;
@ApiModelProperty(value = "密码")
private String password;
}/**
* 添加用户
*
* @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, "添加失败");
}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配置类
*/
@Configuration //项目启动时加载此类
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("阿水的项目接口文挡")
.description("阿水的 Project Swagger2 UserService Interface") //说明信息
.termsOfServiceUrl("http://localhost:8080/swagger-ui/index.html") //文档生成的主页地址
.version("1.0") //文档版本
.build();
}
} http.authorizeRequests().antMatchers( "/swagger-ui.html",
"/swagger-ui/*",
"/swagger-resources/**",
"/v2/api-docs",
"/v3/api-docs",
"/webjars/**").permitAll()
.anyRequest().authenticated(); <dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>以上是SpringBoot整合介面管理工具Swagger怎麼使用的詳細內容。更多資訊請關注PHP中文網其他相關文章！
