一、Swagger的优势
Swagger是一款用于构建、文档化和测试API的开源工具。它具有以下优势：1、自我描述性：Swagger API定义为介绍其资源、操作和参数所需的元数据。这使得Swagger自包含，便于其他人理解和使用。
2、文档化：Swagger UI生成交互式API文档，可立即执行API请求。
3、代码自动生成：Swagger使API描述与代码同步。它支持各种编程语言，可自动生成API客户端SDK、服务端存根和文档。
通过使用Swagger，我们可以将API文档与代码绑定到一起，从而减少误差和不必要的重复工作。
二、Swagger的基本用法
Swagger的基本用法相对简单，只需要在API中定义Swagger注解即可。具体步骤如下：1、添加Swagger依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>2、添加Swagger注解
在需要文档化的对象、方法、字段等上通过注解添加Swagger注解，如下：@Api
@RestController
@RequestMapping(“/api/v1”)
public class UserController {
@ApiOperation(value="获取用户列表", notes="获取所有用户的列表")
@ApiResponses(value={
@ApiResponse(code=200, message="成功"),
@ApiResponse(code=500, message="服务器内部错误")
})
@GetMapping(“/users”)
public List
getUsers() {
return userService.getUsers();
}
}
3、生成文档
执行应用程序，访问http://localhost:8080/v2/api-docs可以获得API的Swagger规范JSON文档。要访问Swagger UI，只需在pom.xml中添加以下依赖项：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>然后，在浏览器中访问http://localhost:8080/swagger-ui.html。您会看到交互式的API文档。
三、使用Swagger进行API测试
Swagger不仅可以生成API文档，还可以直接在Swagger UI中执行API请求。我们只需输入必需的参数并点击“Try it out”按钮。如下面的示例代码所示，我们可以在测试文档中设置请求的参数：
@ApiOperation(value="通过用户ID获取用户信息", notes="通过用户ID获取用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name="id", value="用户ID", required=true, dataType="int", paramType="path")
})
@ApiResponses(value={
@ApiResponse(code=200, message="成功"),
@ApiResponse(code=500, message="服务器内部错误")
})
@GetMapping(“/users/{id}”)
public User getUser(@PathVariable("id") Integer id) {
return userService.getUserById(id);
}四、使用Swagger进行模型定义和格式验证
有时候我们需要通过API定义复杂的数据模型，Swagger也可以帮助我们实现这一点。使用Swagger的@Schema注释可以定义数据模型，@Valid注释可以验证传递给API的模型的格式是否正确。 以下示例代码展示了如何使用@Schema和@Valid注释定义和验证数据模型：@PostMapping("/users")
public ResponseEntity createUser(
@RequestBody @Valid @Schema(description="用户信息", required=true) User user) {
userService.createUser(user);
return ResponseEntity.ok().build();
}
public class User {
@Schema(description="用户ID", example="123", required=true)
@NotNull
private Long id;
@Schema(description="用户名", example="张三", required=true)
@NotNull
private String name;
@Schema(description="用户年龄", example="20", required=true)
@NotNull
private Integer age;
// ...
}五、使用Swagger进行安全定义
在API开发中，安全非常重要。Swagger可以帮助我们定义API的安全需求，并生成相应的安全文档。 以下示例代码展示了如何使用Swagger定义API的安全需求：@ApiResponses(value={
@ApiResponse(code=200, message="成功", response=String.class),
@ApiResponse(code=401, message="未授权"),
@ApiResponse(code=403, message="已禁止"),
@ApiResponse(code=404, message="未找到")
})
@GetMapping("/{id}")
public ResponseEntity getUserById(
@ApiParam(value="用户ID", required=true)@PathVariable("id") Long id,
HttpServletRequest request) {
String authorization = request.getHeader(“Authorization”);
if (authorization == null) {
return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
}
User user = userService.getUserById(id);
if (user == null) {
return ResponseEntity.notFound().build();
}
return ResponseEntity.ok(user);
}
@ApiOperation(value="添加用户", notes="添加用户")
@ApiResponses(value={
@ApiResponse(code=200, message="成功", response=String.class),
@ApiResponse(code=401, message="未授权"),
@ApiResponse(code=403, message="已禁止"),
@ApiResponse(code=404, message="未找到")
})
@PostMapping("/users")
public ResponseEntity createUser(
@ApiParam(value="用户信息", required=true)@RequestBody User user,
HttpServletRequest request) {
String authorization = request.getHeader(“Authorization”);
if (authorization == null) {
return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
}
userService.createUser(user);
return ResponseEntity.ok().build();
}
