Swagger is a series of RESTful API tools. Through Swagger, you can get an interactive document of the project, automatic generation of client SDK and other functions.
The goal of Swagger is to define a standard, language-independent interface for REST APIs, so that people and computers can't see the source code or documents or can't pass network traffic detection. Ability to discover and understand the functionality of various services. When services are defined through Swagger, consumers can interact with remote services with a small amount of implementation logic.
The idea of using Spring Boot to integrate Swagger is to use annotations to mark the information that needs to be displayed in the API document. Swagger will use the annotations marked in the project to mark the information. Generate corresponding API documentation. Swagger is known as the most popular API tool in the world. It provides a complete solution for API management. The factors that need to be considered for API document management are basically included. Here we will explain the most commonly used customization content.
Spring Boot integrates Swagger 3. It is very simple. You only need to introduce dependencies and do basic configuration.
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>Add the @EnableOpenApi annotation to the startup class to enable the swagger api document function
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
语法:
@ApiOperation(value = "",
notes = "",
response = )
属性说明：
value：方法说明标题
notes：方法详细描述
response：方法返回值类型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;
}
}@ApiImplicitParams annotations and @ApiImplicitParam are used for non-object parameters (parameter binding) in methods Use when arriving at a simple type.) Explain
语法:
@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 :参数默认值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 annotation and ApiModelProperty
is used on entity classes to describe the class and is used for parameter reception instructions in entity classes.
@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, "添加失败");
}5. Create the SwaggerConfig configuration class
api() method uses @Bean, Initialized at startup, the instance Docket (Swagger API summary object) is returned. What needs to be noted here is that .apis(RequestHandlerSelectors.basePackage("xxx.yyy.zzz")) specifies the package path that needs to be scanned. Only the Controller under this path Classes will automatically generate Swagger API documentation.
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();
}
}apiInfo() method configuration is relatively important. The basic information displayed on the main configuration page includes title, description, version, terms of service, etc. If you look at the source code of the ApiInfo class, you will also find more configurations such as license support.
4. Springsecurity integrates swagger
http.authorizeRequests().antMatchers( "/swagger-ui.html",
"/swagger-ui/*",
"/swagger-resources/**",
"/v2/api-docs",
"/v3/api-docs",
"/webjars/**").permitAll()
.anyRequest().authenticated();Import the following dependencies, restart the project and access the address: http://localhost:8080/doc.html
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>The above is the detailed content of How to use SpringBoot integrated interface management tool Swagger. For more information, please follow other related articles on the PHP Chinese website!
![[Web front-end] Node.js quick start](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
