2025年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：对单个参数的说明

主要属性：

属性描述 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中”?“后面拼接的每个参数。

实例：

讯享网

参考：

【1】：维基百科：Swagger
【2】：不訉biu：Swagger常用注解
【3】：Ido：swagger常用注解说明
【4】：杨梅泡酒：Swagger Annotation 详解（建议收藏）
【5】：xiaojin21cen ：swagger2 注解说明
【6】：swagger-core wiki:Swagger 2.X Annotations

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

相关推荐