Swagger2
- Swagger2简介
- 1. 整合 Spring Boot
- 2. 创建 Swagger 2 的配置类
- 3. 创建 controller 的接口
- User 实体类代码如下：
- 4. 启动项目，进行测试
- 结语
Swagger2简介
通常在前后端开发中，为了减少一些沟通成本，一般都会构建一份 RESTful API 文档来描述所有的接口信息
Swagger 2 是一个开源软件框架，可以帮助开发人员设计、构建、记录和使用 RESTful Web 服务，它将代码和文档融为一体，
1. 整合 Spring Boot
首先创建 Spring Boot Web 项目，添加 Swagger 2 的相关依赖，代码如下：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>2. 创建 Swagger 2 的配置类
首先通过@EnableSwagger2注解开启 Swagger2
然后在通过 apis 这个方法配置要扫描的 controller 位置，通过 paths 方法配置路径
在 apiInfo 中构建文档的基本信息，比如描述、联系人信息、版本、标题等等
@Configuration
@EnableSwagger2 //此注解表示开启 Swagger 2
public class SwaggerConfig {
@Bean
Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.sang.swagger2.controller")) //配置 controller 的位置
.paths(PathSelectors.any())
.build().apiInfo(new ApiInfoBuilder() // 在 apiInfo 中构建文档的基本信息
.description("员工管理接口测试文档")
.contact(new Contact("小白哥",
"https://gitee.com/jian_bo_bai/dashboard/projects",
"bai211425401@126.com"))
.version("v1.0")
.title("API 测试文档")
.license("Apache2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
.build());
}
}3. 创建 controller 的接口
Swagger 2 配置完成后，接下来就创建 controller 接口测试，代码如下：
注解 | 作用 |
@Api | 此注解用来描述整个 Controller 信息 |
@ApiOperation | 此注解用在开发方法上，用来描述一个方法的基本信息，value是对方法作用的一个简短描述，notes 则用来备注该方法的详细作用 |
@ApiImplicitParam | 此注解用在方法上，用来描述方法的参数，paramType 是指方法参数的类型，可选值有 path(参数获取方式 @PathVariable)query(参数获取方式 @RequestParam)header(参数获取方式 @RequestHeader) body 以及 form ; name 表示参数名称，value 是参数的描述信息，required 表示该字段是否必填，defaultValue 表示该字段的默认值 |
@ApiResponse | 此注解是对相应结果的描述，code 表示响应码， message 表示对应的描述，若有多个 @ApiResponse 则可以放在一个 @ApiResponses 中 |
@ApiIgnore | 此注解表示不对某个接口生成文档 |
@RestController
@Api(tags = "用户数据接口") //此注解用来描述当前 controller 的信息
public class UserController {
@ApiOperation(value = "查询用户",notes = "根据 id 查询用户")
@ApiImplicitParam(paramType = "path",name = "id",value = "用户id",required = true)
@GetMapping("/user/{id}")
public String getUserById(@PathVariable Integer id) {
return "/user/" + id;
}
@ApiResponses({
@ApiResponse(code = 200,message = "删除成功！"),
@ApiResponse(code = 500,message = "删除失败！")})
@ApiOperation(value = "删除用户",notes = "通过 id 删除用户")
@DeleteMapping("/user/{id}")
public Integer deleteUserById(@PathVariable Integer id) {
return id;
}
@ApiOperation(value = "添加用户",notes = "添加一个用户，传入用户名和地址")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "query",name = "username",value = "用户名",required = true,defaultValue = "sang"),
@ApiImplicitParam(paramType = "query",name = "address",value = "用户地址",required = true,defaultValue = "shenzhen")})
@PostMapping("/user")
public String addUser(@RequestParam String username,@RequestParam String address) {
return username + ":" + address;
}
@ApiOperation(value = "修改用户",notes = "修改用户，传入用户信息")
@PutMapping("/user")
public String updateUser(@RequestBody User user) {
return user.toString();
}
@GetMapping("/ignore")
@ApiIgnore
public void ingoreMethod() {}
}User 实体类代码如下：
@ApiModel(value = "用户实体类",description = "用户信息描述类")
public class User implements Serializable {
@ApiModelProperty(value = "用户名")
private String username;
@ApiModelProperty(value = "用户地址")
private String address;
public User() {
super();
}
public User(String username, String address) {
this.username = username;
this.address = address;
}
@Override
public String toString() {
return "User{" +
"username='" + username + '\'' +
", address='" + address + '\'' +
'}';
}
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public String getAddress() {
return address;
}
public void setAddress(String address) {
this.address = address;
}
}4. 启动项目，进行测试
启动项目，在浏览器中输入 localhost:8080/swagger-ui.html 即可看到效果图
展开用户数据接口，即可看到所有接口的描述
