swagger常见注解

常见注解

注解	位置	描述	参数
@Api	类级别	用于描述整个 API 文档的信息，如标题、描述等。	- tags：API 所属的标签列表。 - value：API 的简要描述。
@ApiOperation	方法级别	用于描述 API 操作（方法）的信息，包括方法的描述、HTTP 方法、URL 等。	- value：API 操作的简要描述。 - notes：API 操作的详细说明。 - httpMethod：HTTP 方法，如 GET、POST 等。 - response：API 操作的返回类型。
@ApiParam	方法参数级别	用于描述方法参数的信息，包括参数名称、是否必需、描述等。	- value：参数的描述。 - name：参数的名称。 - required：参数是否必需，默认为 false。 - defaultValue：参数的默认值。
@ApiModel	类级别	用于描述数据模型（DTO）的信息。	- value：数据模型的名称。 - description：数据模型的描述。
@ApiModelProperty	属性级别	用于描述数据模型的属性信息，包括属性名称、描述、是否必需等。	- value：属性的描述。 - name：属性的名称。 - required：属性是否必需，默认为 false。 - example：属性的示例值。
@ApiResponse	方法级别	用于描述 API 操作的响应信息，包括状态码、描述等。	- code：HTTP 响应状态码。 - message：响应的描述信息。 - response：响应的数据类型。

代码示例

import org.springframework.web.bind.annotation.*;
import io.swagger.annotations.*;

@RestController
@Api(tags = "用户管理相关接口")
@RequestMapping("/users")
public class UserController {

    @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户信息")
    @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    @GetMapping("/{userId}")
    public User getUser(@PathVariable Long userId) {
        // 获取用户逻辑...
    }

    @ApiOperation(value = "创建用户", notes = "根据用户信息创建用户")
    @ApiResponses(value = {
            @ApiResponse(code = 201, message = "用户创建成功"),
            @ApiResponse(code = 400, message = "请求参数有误"),
            @ApiResponse(code = 500, message = "服务器内部错误")
    })
    @PostMapping("/")
    public ResponseEntity<Void> createUser(@RequestBody User user) {
        // 创建用户逻辑...
        return ResponseEntity.status(HttpStatus.CREATED).build();
    }

    @ApiOperation(value = "更新用户信息", notes = "根据用户ID更新用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "Long", paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用户信息", required = true, dataType = "User")
    })
    @PutMapping("/{userId}")
    public ResponseEntity<Void> updateUser(@PathVariable Long userId, @RequestBody User user) {
        // 更新用户逻辑...
        return ResponseEntity.ok().build();
    }

    @ApiOperation(value = "删除用户", notes = "根据用户ID删除用户")
    @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    @DeleteMapping("/{userId}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long userId) {
        // 删除用户逻辑...
        return ResponseEntity.ok().build();
    }
}

在上面的示例中，使用了 Swagger 注解来描述用户管理相关的接口：

• @Api: 描述了整个 UserController 类的信息，指定了标签为“用户管理相关接口”。
• @ApiOperation: 描述了各个 API 操作的信息，包括方法的简要描述、详细说明等。
• @ApiImplicitParam、@ApiImplicitParams: 用于描述方法参数的信息，包括参数名称、描述、是否必需等。
• @ApiResponses、@ApiResponse: 用于描述 API 操作的响应信息，包括状态码、描述等。