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 操作的响应信息,包括状态码、描述等。
  • 9
    点赞
  • 9
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值