Java工程师知识树 / 项目学习
概念和作用
概念:
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务.
作用:
- 支持 API 自动生成同步的在线文档.另外一种方式,使用编写Office文档来提供接口文档.
- 提供 Web 页面在线测试 API.另外一种常用方式使用postman测试接口.
SpringBoot集成Swagger
集成最低要求是可以使用,类似一个Hello World项目.
注:
- jdk 需要使用1.8或以上版本
- swagger2的3.0版本的访问地址/swagger-ui/index.html
2.x之前访问地址/swagger-ui.html - maven文件配置
io.springfox
springfox-swagger2
3.0.0
io.springfox
springfox-swagger-ui
3.0.0
io.springfox
springfox-boot-starter
3.0.0
- Application启动应用类上面加入@EnableOpenApi注解
@EnableOpenApi// 只需要在Application启动应用类配置
@SpringBootApplication
public class Swagger3Application {
public static void main(String[] args) {
SpringApplication.run(Swagger3Application.class, args);
}
}
项目启动后的效果为:
SpringBoot配置Swagger
自定义配置类
import org.apache.commons.lang3.reflect.FieldUtils;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.lang.reflect.Field;
import java.util.List;
@Configuration
public class Swagger3Config implements WebMvcConfigurer {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select() // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
/*
basePackage(final String basePackage) // 根据包路径扫描接口
any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class annotation)
*/
.apis(RequestHandlerSelectors.basePackage("com.study.swagger3.controller"))// basePackage 根据包路径扫描接口
/*
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制
*/
.paths(PathSelectors.any())// 配置如何通过path过滤,即这里扫描所有请求 any none ant regex
.build();
}
/**
* API 页面上半部分展示信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger3接口文档")
.description("文档描述")
.contact(new Contact("hughJin", "#", "[email protected]"))
.version("1.0")
.build();
}
/**
* 通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息
*/
@Override
public void addInterceptors(InterceptorRegistry registry) {
try {
Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
List registrations = (List) ReflectionUtils.getField(registrationsField, registry);
if (registrations != null) {
for (InterceptorRegistration interceptorRegistration : registrations) {
interceptorRegistration
.excludePathPatterns("/swagger**/**")
.excludePathPatterns("/webjars/**")
.excludePathPatterns("/v3/**")
.excludePathPatterns("/doc.html");
}
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
常用Swagger注解与说明
| Swagger注解 | 简单说明 |
|---|---|
| @Api(tags = “xxx模块说明”) | 作用在模块类上 |
| @ApiOperation(“xxx接口说明”) | 作用在接口方法上 |
| @ApiModel(“xxxPOJO说明”) | 作用在模型类上：如VO、BO |
| @ApiModelProperty(value = “xxx属性说明”,hidden = true) | 作用在类方法和属性上，hidden设置为true可以隐藏该属性 |
| @ApiParam(“xxx参数说明”) | 作用在参数、方法和字段上，类似@ApiModelProperty |
Swagger注解代码实例
import com.study.swagger3.dto.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
@Api(value = "@Api：用在控制器类上，表示对类的说明", tags = "Swagger测试之用户信息管理API")
@RestController
@RequestMapping("/user")
public class SwaggerController {
@ApiIgnore // 忽略这个API
@GetMapping("/hello")
public String hello() {
return "hello";
}
@GetMapping(value = "/swaggerGet/{name}")
@ApiOperation(value = "接口方法说明", notes = "@ApiOperation：用在请求的方法上，说明方法的用途、作用")
@ApiImplicitParam(name = "name", value = "@ApiImplicitParams：用在请求的方法上，表示一组参数说明",required = true, dataType = "String", paramType = "path")
public String swaggerGet( @PathVariable String name) {
return "name="+name;
}
@PostMapping(value = "/swaggerPost")
@ApiOperation(value = "新增用户", notes = "@ApiOperation Swagger测试RESTful之POST请求测试入参一个POJO（JSON格式）")
public User swaggerGet(@RequestBody User user) {
return user;
}
@GetMapping(value = "/swaggerApiParam")
@ApiOperation(value = "测试参数")
public User swaggerApiParam(@ApiParam(value = "主键查询" ,required = true) String id) {
return new User();
}
}
//////////////////////////////////////
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
@ApiModel("实体类 @ApiModel：用于响应类上（POJO实体类），描述一个返回响应数据的信息（描述POJO类请求或响应的实体说明）")
public class User implements Serializable {
private static final long serialVersionUID = -6627165976923138391L;
@ApiModelProperty(value = "用户名 @ApiModelProperty：用在POJO属性上，描述响应类的属性说明", dataType = "String", name = "username", example = "hughJin")
private String username;
@ApiModelProperty(value = "账户密码", dataType = "String", name = "password", example = "123456")
private String password;
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
@Override
public String toString() {
return "User{" +
"username='" + username + '\'' +
", password='" + password + '\'' +
'}';
}
}
集成knife4j
com.github.xiaoymin
knife4j-spring-boot-starter
3.0.2
com.github.xiaoymin
knife4j-springdoc-ui
3.0.2
集成后访问路径为：/doc.html#/home
集成后效果为：
swagger3项目源代码路径：
链接：https://pan.baidu.com/s/1YC6tKQmknaPJ0ESxbWjpbA
提取码：tidu