Spring Boot 中使用 Swagger3.0.0 注解
作者：刘大猫
- 2025-11-26 黑龙江
本文字数：2087 字
阅读完需：约 7 分钟
四、注解说明
注意：注解中其实会有很多的属性，该文章只列出部分常用的属性而已，其他不常用属性请查看其他人博客！
@Api
@Api
@Api : 位置：用在请求的类上，例如Controller， 作用：说明该类的主要作用。 参数说明：@Api("tags":"", "value":"", "description ":"") tags：说明该类的作用，参数是个数组，可以填多个。 value="该参数没什么意义，在UI界面上不显示，所以不用配置" description = "用户基本信息操作"
复制代码
代码示例如下：
@RestController@RequestMapping("/swagger")@Api(tags = "用户管理")@Slf4jpublic class SwaggerController {}
复制代码
网站效果展示：
<hr>
@ApiOperation
@ApiOperation
@ApiOperation： 位置：用在请求方法上 作用：说明方法的用途、作用 参数说明：@ApiOperation("value":"", "notes":"", "tags ":"") value="方法的用途和作用" notes="方法的注意事项和备注" tags：说明该方法的作用， 参数是个数组，可以填多个。例如格式：tags={"作用1","作用2"}
复制代码
代码示例如下：
@GetMapping("/getList")@ApiOperation(value = "分页查询", notes = "分页查询的注意事项和备注", tags = {"说明该方法的作用1,说明该方法的作用2"})public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){
复制代码
网站效果展示：
<hr>
@ApiImplicitParams
@ApiImplicitParams
@ApiImplicitParams: 位置：用在请求方法上 作用：包含多@ApiImplicitParam，包含一组参数说明。 参数说明：@ApiImplicitParams({@ApiImplicitParam("name":"", "value":"", "dataType":"", "paramType":"", "required":"")...})
复制代码
代码示例如下：
@GetMapping("/getList")@ApiOperation(value = "分页查询", notes = "分页查询的注意事项和备注", tags = {"说明该方法的作用1,说明该方法的作用2"})@ApiImplicitParams({ @ApiImplicitParam(name = "pageNo", value = "当前页码，从1开始", paramType = "query", required = true, dataType="int") , @ApiImplicitParam(name = "pageSize", value = "每页显示记录数", paramType = "query",required = true, dataType="int") , })public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){
复制代码
@ApiImplicitParam
@ApiImplicitParam
@ApiImplicitParam： 位置：用在请求方法上 作用：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面说明 参数说明：@ApiImplicitParam("name":"", "value":"", "dataType":"", "paramType":"", "required":"") name="参数名称" value="参数说明" dataType="数据类型"，默认String required=true 参数是否必选 paramType="query" 表示参数放在哪里，查询参数类型，这里有几种形式： header --> 请求参数的获取：@RequestHeader，参数在 request headers 里边提交 query --> 请求参数的获取：@RequestParam，直接跟参数，完成自动映射赋值 path（用于 restful 接口）--> 请求参数的获取：@PathVariable，以地址的形式提交数据 body（不常用）--> 以流的形式提交 仅支持 POST form（不常用）--> 以 form 表单的形式提交 仅支持 POST
复制代码
代码示例如下：
@GetMapping("/getList")@ApiOperation(value = "分页查询", notes = "分页查询的注意事项和备注", tags = {"说明该方法的作用1,说明该方法的作用2"})@ApiImplicitParams({ @ApiImplicitParam(name = "pageNo", value = "当前页码，从1开始", paramType = "query", required = true, dataType="int") , @ApiImplicitParam(name = "pageSize", value = "每页显示记录数", paramType = "query",required = true, dataType="int") , })public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){
复制代码
网站效果展示：
<hr>
@ApiResponses
@ApiResponses
@ApiResponses：用在请求的方法上，表示一组响应
复制代码
代码示例如下：
@GetMapping("/getList")@ApiResponses({ @ApiResponse(code=400,message="请求参数及格式不对"), @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对") })public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){
复制代码
@ApiResponse
@ApiResponse
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400 message：信息，例如"请求参数没填好" response：抛出异常的类
复制代码
代码示例如下：
@GetMapping("/getList")@ApiResponses({ @ApiResponse(code=400,message="请求参数及格式不对"), @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")})public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){
复制代码
网站效果展示：
<hr>
划线
评论
复制
发布于: 刚刚阅读数: 4
刘大猫
关注
还未添加个人签名 2022-08-23 加入
还未添加个人简介
评论