Swagger2 最全注解说明

2024-05-07 00:38
文章标签 说明 注解 swagger2 最全

本文主要是介绍Swagger2 最全注解说明,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

1,swagger2 注解整体说明

2,@API: 请求类的说明

3,@ApiOperation: 方法的说明

3.1,@ApiImplicitParams,@ApiImplicitParam: 方法参数的说明

4,@ApiResponses,@ApiResponse: 方法返回值的说明

5,@ApiModel: 用于 JavaBean 上面, 表示一个 JavaBean(如: 响应数据) 的信息

5.1,@ApiModelProperty: 用在 JavaBean 类的属性上面, 说明属性的含义

1,swagger2 注解整体说明

用于 controller 类上:

注解说明
@Api对请求类的说明

用于方法上面 (说明参数的含义):

注解说明
@ApiOperation方法的说明
@ApiImplicitParams、@ApiImplicitParam方法的参数的说明;@ApiImplicitParams 用于指定单个参数的说明

用于方法上面 (返回参数或对象的说明):

注解说明
@ApiResponses、@ApiResponse方法返回值的说明 ;@ApiResponses 用于指定单个参数的说明

对象类:

注解说明
@ApiModel用在 JavaBean 类上,说明 JavaBean 的 用途
@ApiModelProperty用在 JavaBean 类的属性上面,说明此属性的的含议

2,@API: 请求类的说明

@API: 放在 请求的类上, 与 @Controller 并列, 说明类的作用, 如用户模块, 订单类等.

 
  1. tags="说明该类的作用"
  2. value="该参数没什么意义, 所以不需要配置"

示例:

  1. @API(tags="订单模块")
  2. @Controller
  3. public class OrderController {
  4.  
  5. }

@API 其它属性配置:

属性名称备注
valueurl 的路径值
tags如果设置这个值、value 的值会被覆盖
description对 api 资源的描述
basePath       基本路径
position            如果配置多个 Api 想改变显示的顺序位置
produces如, “application/json, application/xml”
consumes 如, “application/json, application/xml”
protocols协议类型,如: http, https, ws, wss.
authorizations高级特性认证时配置
hidden配置为 true ,将在文档中隐藏

3,@ApiOperation: 方法的说明

  1. @ApiOperation:"用在请求的方法上, 说明方法的作用"
  2. value="说明方法的作用"
  3. notes="方法的备注说明"

3.1,@ApiImplicitParams,@ApiImplicitParam: 方法参数的说明

@ApiImplicitParams: 用在请求的方法上, 包含一组参数说明

@ApiImplicitParam: 对单个参数的说明

name: 参数名

value: 参数的汉字说明, 解释

required: 参数是否必须传

paramType: 参数放在哪个地方

. header --> 请求参数的获取:@RequestHeader

. query --> 请求参数的获取:@RequestParam

. path(用于 restful 接口)--> 请求参数的获取:@PathVariable

  1. . body(请求体)--> @RequestBody User user
  2. . form(普通表单提交)

dataType: 参数类型, 默认 String, 其它值 dataType="Integer"

defaultValue: 参数的默认值

示列:

  1. @API(tags="用户模块")
  2. @Controller
  3. public class UserController {
  4. @ApiOperation(value="用户登录",notes="随边说点啥")
  5. @ApiImplicitParams({
  6. @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
  7. @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
  8. @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
  9. })
  10. @PostMapping("/login")
  11. public JsonResult login(@RequestParam String mobile, @RequestParam String password,
  12. @RequestParam Integer age){
  13. //...
  14. return JsonResult.ok(map);
  15. }
  16. }

4,@ApiResponses,@ApiResponse: 方法返回值的说明

@ApiResponses: 方法返回对象的说明

@ApiResponse: 每个参数的说明

code: 数字, 例如 400

message: 信息, 例如 "请求参数没填好"

response: 抛出异常的类

示例:

  1. @API(tags="用户模块")
  2. @Controller
  3. public class UserController {
  4. @ApiOperation("获取用户信息")
  5. @ApiImplicitParams({
  6. @ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户 Id")
  7. })
  8. @ApiResponses({
  9. @ApiResponse(code = 400, message = "请求参数没填好"),
  10. @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
  11. })
  12. @ResponseBody
  13. @RequestMapping("/list")
  14. public JsonResult list(@RequestParam String userId) {
  15. ...
  16. return JsonResult.ok().put("page", pageUtil);
  17. }
  18. }

5,@ApiModel: 用于 JavaBean 上面, 表示一个 JavaBean(如: 响应数据) 的信息

@ApiModel: 用于 JavaBean 的类上面, 表示此 JavaBean 整体的信息

(这种一般用在 post 创建的时候, 使用 @RequestBody 这样的场景,

请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 )

5.1,@ApiModelProperty: 用在 JavaBean 类的属性上面, 说明属性的含义

示例:

  1. @ApiModel(description= "返回响应数据")
  2. public class RestMessage implements Serializable{
  3. @ApiModelProperty(value = "是否成功")
  4. private boolean success=true;
  5. @ApiModelProperty(value = "返回对象")
  6. private Object data;
  7. @ApiModelProperty(value = "错误编号")
  8. private Integer errCode;
  9. @ApiModelProperty(value = "错误信息")
  10. private String message;
  11. /* getter/setter 略 */
  12. }

这篇关于Swagger2 最全注解说明的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!


原文地址:
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.chinasem.cn/article/965842

相关文章

Spring @RequestMapping 注解及使用技巧详解

《Spring@RequestMapping注解及使用技巧详解》@RequestMapping是SpringMVC中定义请求映射规则的核心注解,用于将HTTP请求映射到Controller处理方法... 目录一、核心作用二、关键参数说明三、快捷组合注解四、动态路径参数(@PathVariable)五、匹配请

Spring中管理bean对象的方式(专业级说明)

《Spring中管理bean对象的方式(专业级说明)》在Spring框架中,Bean的管理是核心功能,主要通过IoC(控制反转)容器实现,下面给大家介绍Spring中管理bean对象的方式,感兴趣的朋... 目录1.Bean的声明与注册1.1 基于XML配置1.2 基于注解(主流方式)1.3 基于Java

SpringCloud中的@FeignClient注解使用详解

《SpringCloud中的@FeignClient注解使用详解》在SpringCloud中使用Feign进行服务间的调用时,通常会使用@FeignClient注解来标记Feign客户端接口,这篇文章... 在Spring Cloud中使用Feign进行服务间的调用时,通常会使用@FeignClient注解

Java 关键字transient与注解@Transient的区别用途解析

《Java关键字transient与注解@Transient的区别用途解析》在Java中,transient是一个关键字,用于声明一个字段不会被序列化,这篇文章给大家介绍了Java关键字transi... 在Java中,transient 是一个关键字,用于声明一个字段不会被序列化。当一个对象被序列化时,被

Swagger2与Springdoc集成与使用详解

《Swagger2与Springdoc集成与使用详解》:本文主要介绍Swagger2与Springdoc集成与使用方式,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐... 目录1. 依赖配置2. 基础配置2.1 启用 Springdoc2.2 自定义 OpenAPI 信息3.

Spring Cache注解@Cacheable的九个属性详解

《SpringCache注解@Cacheable的九个属性详解》在@Cacheable注解的使用中,共有9个属性供我们来使用,这9个属性分别是:value、cacheNames、key、key... 目录1.value/cacheNames 属性2.key属性3.keyGeneratjavascriptor

使用@Cacheable注解Redis时Redis宕机或其他原因连不上继续调用原方法的解决方案

《使用@Cacheable注解Redis时Redis宕机或其他原因连不上继续调用原方法的解决方案》在SpringBoot应用中,我们经常使用​​@Cacheable​​注解来缓存数据,以提高应用的性能... 目录@Cacheable注解Redis时,Redis宕机或其他原因连不上,继续调用原方法的解决方案1

Spring Boot 常用注解整理(最全收藏版)

《SpringBoot常用注解整理(最全收藏版)》本文系统整理了常用的Spring/SpringBoot注解,按照功能分类进行介绍,每个注解都会涵盖其含义、提供来源、应用场景以及代码示例,帮助开发... 目录Spring & Spring Boot 常用注解整理一、Spring Boot 核心注解二、Spr

Java Jackson核心注解使用详解

《JavaJackson核心注解使用详解》:本文主要介绍JavaJackson核心注解的使用,​​Jackson核心注解​​用于控制Java对象与JSON之间的序列化、反序列化行为,简化字段映射... 目录前言一、@jsonProperty-指定JSON字段名二、@JsonIgnore-忽略字段三、@Jso

Spring Boot 常用注解详解与使用最佳实践建议

《SpringBoot常用注解详解与使用最佳实践建议》:本文主要介绍SpringBoot常用注解详解与使用最佳实践建议,本文给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要... 目录一、核心启动注解1. @SpringBootApplication2. @EnableAutoConfi