Swagger接口文档注解使用说明规范

繁星皆为尘>-<

于 2023-06-29 11:31:09 发布

阅读量185

点赞数

文章标签： java spring boot

本文链接：https://blog.csdn.net/qq_30035843/article/details/131453049

版权

文章介绍了如何使用Swagger的注解如@Api,@ApiModel,@ApiModelProperty,@ApiParam等来标注Java类和方法，以生成详细的RESTfulAPI文档，包括接口作用、模型说明、参数解释和响应信息。

摘要由CSDN通过智能技术生成

//@Api 用在类上，说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源
@Api(tags={"用户接口"})
@RestController
public class UserController

//@ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明。
@ApiModel(value = "com.biancheng.auth.param.AddUserParam", description = "新增用户参数")
public class AddUserParam {}

//@ApiModelProperty() 用于字段，表示对 model 属性的说明。
@ApiModelProperty(value = "ID")
private String id;

@ApiParam 用于 Controller 中方法的参数说明。value：参数说明 required：是否必填
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {}

//@ApiOperation 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义。
@ApiOperation(value="新增用户", notes="详细描述")
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {}

//@ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个 @ApiResponse。
@ApiResponses({ @ApiResponse(code = 200, message = "OK", response = UserDto.class) })
@PostMapping("/user")
public UserDto addUser(@ApiParam(value = "新增用户参数", required = true) @RequestBody AddUserParam param) {}

//用于方法上，为单独的请求参数进行说明。使用方式代码如下所示。
@ApiImplicitParams({
//name：参数名，对应方法中单独的参数名称。value：参数中文说明。required：是否必填。paramType：参数类型，取值为 path、query、body、header、form。dataType：参数数据类型。defaultValue：默认值。
@ApiImplicitParam(name = "id", value = "用户ID", dataType = "string", paramType = "query", required = true, defaultValue = "1")
})
@ApiResponses({ @ApiResponse(code = 200, message = "OK", response = UserDto.class) })
@GetMapping("/user")
public UserDto getUser(@RequestParam("id") String id) {}