Spring Fox简介
Springfox是一个用于在Spring应用程序中生成Swagger文档的开源库。它提供了一组注解和工具,可以将你的API代码和文档整合在一起,方便生成和展示API的Swagger文档。
使用Springfox,你可以在Spring Boot项目中集成Swagger,并通过Swagger UI查看和测试API。它提供了一些注解,如 @Api
、@ApiOperation
、@ApiParam
等,用于定义API的基本信息、操作和参数。通过这些注解,你可以准确地描述每个API的功能、输入和输出,生成详细的API文档。
Springfox还提供了一些可自定义的配置选项,你可以根据需要进行配置,以满足特定的文档需求。例如,你可以配置文档的标题、描述、版本号等信息,控制哪些API暴露给Swagger进行文档生成,以及如何处理请求和响应的数据类型等。
Springfox是一个用于在Spring应用程序中生成Swagger文档的工具库,它简化了API文档的生成和管理过程,使开发人员能够更轻松地创建和维护API文档。
案例
在此基础之上,我们添加相关依赖:
xml
<dependencies>
<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>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
<repositories>
<repository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>jcenter-releases</id>
<name>jcenter</name>
<url>http://jcenter.bintray.com</url>
</repository>
</repositories>
利用相关注解在实体类进行相关校验,这里也使用Spring Boot中使用JSR-303实现请求参数校验的JSR-303校验,如果不了解JSR-303校验的可以去了解一下。
java
@ApiModel("用户基本信息")
public class User {
@ApiModelProperty("姓名")
@Size(max = 20)
private String name;
@ApiModelProperty("年龄")
@Max(150)
@Min(1)
private Integer age;
@NotNull
private String address;
@Pattern(regexp = "^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)+$")
private String email;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
public String getAddress() {
return address;
}
public void setAddress(String address) {
this.address = address;
}
public String getEmail() {
return email;
}
public void setEmail(String email) {
this.email = email;
}
@Override
public String toString() {
return "User{" +
"name='" + name + '\'' +
", age=" + age +
", address='" + address + '\'' +
", email='" + email + '\'' +
'}';
}
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (o == null || getClass() != o.getClass()) return false;
User user = (User) o;
return Objects.equals(name, user.name) && Objects.equals(age, user.age) && Objects.equals(address, user.address) && Objects.equals(email, user.email);
}
@Override
public int hashCode() {
return Objects.hash(name, age, address, email);
}
public User(String name, Integer age, String address, String email) {
this.name = name;
this.age = age;
this.address = address;
this.email = email;
}
public User() {
}
}
此外启动类也需要加一个@EnableOpenApi
注解。
接下来我们就在UserController类里边使用相关注解完成我们的SpringFox和Swagger文档生成:
java
@Api(tags="用户管理")
@RestController
public class UserController {
@ApiOperation("创建用户")
@PostMapping("/users")
public User create(@RequestBody @Valid User user) {
return user;
}
@ApiOperation("用户详情")
@GetMapping("/users/{id}")
public User findById(@PathVariable Long id) {
return new User("bbb", 21, "上海", "aaa@bbb.com");
}
@ApiOperation("用户列表")
@GetMapping("/users")
public List<User> list(@ApiParam("查看第几页") @RequestParam int pageIndex,
@ApiParam("每页多少条") @RequestParam int pageSize) {
List<User> result = new ArrayList<>();
result.add(new User("aaa", 50, "北京", "aaa@ccc.com"));
result.add(new User("bbb", 21, "广州", "aaa@ddd.com"));
return result;
}
@ApiIgnore
@DeleteMapping("/users/{id}")
public String deleteById(@PathVariable Long id) {
return "delete user : " + id;
}
}
- 启动项目
- 浏览器访问:http://localhost:8080/swagger-ui.html