2026年swagger注解大全（swaggerui注解）

在这里插入图片描述

Swagger是一个开放源代码软件框架，由大型工具生态系统支持，可帮助开发人员设计，构建，记录和使用RESTful Web服务。尽管大多数用户通过Swagger UI工具识别Swagger，但是Swagger工具集包括对自动文档，代码生成和测试用例生成的支持。

@Api 注解用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

主要属性如下：

实例:

@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。

主要属性：

属性描述 value url的路径值 tags 如果设置这个值、value的值会被覆盖 description 对api资源的描述 basePath 基本路径可以不配置 position 如果配置多个Api 想改变显示的顺序位置 produces For example, "application/json, application/xml" consumes For example, "application/json, application/xml" protocols Possible values: http, https, ws, wss. authorizations 高级特性认证时配置 hidden 配置为true 将在文档中隐藏 response 返回的对象 responseContainer 这些对象是有效的 "List", "Set" or "Map".，其他无效 httpMethod "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH" code http的状态码默认 200 extensions 扩展属性

实例：

@ApiParam作用于请求方法上，定义api参数的注解。

主要属性：

属性描述 name 属性名称 value 属性值 defaultValue 默认属性值 allowableValues 可以不配置 required 是否属性必填 access 不过多描述 allowMultiple 默认为false hidden 隐藏该属性 example 举例子

实例：

@ApiImplicitParams、@ApiImplicitParam也可以定义参数.

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明

主要属性：

属性描述 name 参数名 value 参数的说明、描述 required 参数是否必须必填 paramType 参数放在哪个地方
query --> 请求参数的获取：@RequestParam
header --> 请求参数的获取：@RequestHeader
path（用于restful接口）--> 请求参数的获取：@PathVariable
body（请求体）--> @RequestBody User user
form（普通表单提交）

dataType 参数类型，默认String，其它值dataType="Integer" defaultValue 参数的默认值

实例：

@ApiResponses、@ApiResponse进行方法返回对象的说明。

主要属性：

属性描述 code 数字，例如400 message 信息，例如"请求参数没填好" response 抛出异常的类

实例：

@ApiModel用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）。

@ApiModelProperty用来描述一个Model的属性。

实例：

@PathVariable用于获取get请求url路径上的参数，即参数绑定的作用，通俗的说是url中"?"前面绑定的参数。

实例：

@RequestParam用于获取前端传过来的参数，可以是get、post请求，通俗的说是url中"?"后面拼接的每个参数。

实例：

参考：

今天的文章 2026年swagger注解大全（swaggerui注解）分享到此就结束了，感谢您的阅读。

2026年swagger注解大全（swaggerui注解）

相关推荐