Swagger注解-CSDN博客

本文链接：https://blog.csdn.net/jam_yin/article/details/131225708

Swagger是一个开源的API文档工具，可以自动生成API文档，方便开发人员查看和调用API接口。在Java开发中，我们可以使用Swagger注解来描述API接口和参数，从而生成API文档。本文将详细介绍Swagger注解的使用方法和常见示例。

一、Swagger注解简介

Swagger注解是一组用于描述API接口和参数的注解，主要包括以下几种：

@Api：描述API接口的基本信息，包括接口名称、描述、作者等。
@ApiOperation：描述API接口的操作方法，包括HTTP请求方法、接口路径、接口说明等。
@ApiParam：描述API接口的参数信息，包括参数名称、参数类型、参数说明等。
@ApiModel：描述API接口的返回结果类型，包括返回结果的数据结构、返回结果的说明等。
@ApiModelProperty：描述API接口返回结果的属性信息，包括属性名称、属性类型、属性说明等。

使用Swagger注解可以让我们更方便地描述API接口和参数，从而生成规范的API文档，提高开发效率和代码质量。

二、Swagger注解详解

1. @Api

@Api注解用于描述API接口的基本信息，包括接口名称、描述、作者等。具体使用方法如下：

@Api(value = "UserController", description = "用户管理接口", tags = {"用户管理"})
@RestController
@RequestMapping("/user")
public class UserController {
    // ...
}

value：接口名称，必填项。
description：接口描述，非必填项。
tags：接口标签，用于对接口进行分类，非必填项。

2. @ApiOperation

@ApiOperation注解用于描述API接口的操作方法，包括HTTP请求方法、接口路径、接口说明等。具体使用方法如下：

@ApiOperation(value = "获取用户列表", notes = "获取所有用户列表")
@GetMapping("/list")
public List<User> getUserList() {
    // ...
}

value：接口名称，必填项。
notes：接口说明，非必填项。
httpMethod：HTTP请求方法，非必填项，默认为GET。
response：接口返回结果类型，非必填项。
responseContainer：接口返回结果容器类型，非必填项。

3. @ApiParam

@ApiParam注解用于描述API接口的参数信息，包括参数名称、参数类型、参数说明等。具体使用方法如下：

@GetMapping("/get")
public User getUserById(@ApiParam(name = "id", value = "用户ID", required = true) @RequestParam Long id) {
    // ...
}

name：参数名称，必填项。
value：参数说明，非必填项。
required：参数是否必填，非必填项，默认为false。
dataType：参数类型，非必填项。
defaultValue：参数默认值，非必填项。

4. @ApiModel

@ApiModel注解用于描述API接口的返回结果类型，包括返回结果的数据结构、返回结果的说明等。具体使用方法如下：

@ApiModel(value = "User", description = "用户信息")
public class User {
    @ApiModelProperty(value = "用户ID")
    private Long id;
    
    @ApiModelProperty(value = "用户名")
    private String username;
    
    @ApiModelProperty(value = "用户密码")
    private String password;
    
    // ...
}

value：返回结果类型名称，必填项。
description：返回结果类型说明，非必填项。

5. @ApiModelProperty

@ApiModelProperty注解用于描述API接口返回结果的属性信息，包括属性名称、属性类型、属性说明等。具体使用方法如下：

@ApiModel(value = "User", description = "用户信息")
public class User {
    @ApiModelProperty(value = "用户ID")
    private Long id;
    
    @ApiModelProperty(value = "用户名")
    private String username;
    
    @ApiModelProperty(value = "用户密码")
    private String password;
    
    // ...
}

value：属性说明，必填项。
name：属性名称，非必填项，默认为属性的变量名。
dataType：属性类型，非必填项，默认为属性的类型。
required：属性是否必填，非必填项，默认为false。
example：属性示例值，非必填项。

三、Swagger注解示例

下面是一个使用Swagger注解的示例：

@Api(value = "UserController", description = "用户管理接口", tags = {"用户管理"})
@RestController
@RequestMapping("/user")
public class UserController {
    @ApiOperation(value = "获取用户列表", notes = "获取所有用户列表")
    @GetMapping("/list")
    public List<User> getUserList() {
        // ...
    }
    
    @ApiOperation(value = "根据ID获取用户信息", notes = "根据ID获取用户信息")
    @GetMapping("/get")
    public User getUserById(@ApiParam(name = "id", value = "用户ID", required = true) @RequestParam Long id) {
        // ...
    }
    
    @ApiOperation(value = "添加用户", notes = "添加用户")
    @PostMapping("/add")
    public void addUser(@ApiParam(name = "user", value = "用户信息", required = true) @RequestBody User user) {
        // ...
    }
    
    @ApiOperation(value = "更新用户信息", notes = "更新用户信息")
    @PutMapping("/update")
    public void updateUser(@ApiParam(name = "user", value = "用户信息", required = true) @RequestBody User user) {
        // ...
    }
    
    @ApiOperation(value = "删除用户", notes = "删除用户")
    @DeleteMapping("/delete")
    public void deleteUser(@ApiParam(name = "id", value = "用户ID", required = true) @RequestParam Long id) {
        // ...
    }
}

@ApiModel(value = "User", description = "用户信息")
public class User {
    @ApiModelProperty(value = "用户ID")
    private Long id;
    
    @ApiModelProperty(value = "用户名")
    private String username;
    
    @ApiModelProperty(value = "用户密码")
    private String password;
    
    // ...
}

在上面的示例中，我们使用了@Api、@ApiOperation、@ApiParam、@ApiModel和@ApiModelProperty注解来描述API接口和参数，从而生成规范的API文档。