Swagger使用和注释介绍

一:介绍

1、什么是Swagger

Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

作用

  • 接口文档在线自动生成
  • 功能测试

Swagger是一组开源项目,其中主要要项目如下:

  • Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

  • Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。

  • Swagger-js: 用于JavaScript的Swagger实现。

  • Swagger-node-express: Swagger模块,用于node.js的Express web应用框架。

  • Swagger-ui:一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档。

  • Swagger-codegen:一个模板驱动引擎,通过分析用户Swagger资源声明以各种语言生成客户端代码。

2、在Spring使用Swagger

在Spring中集成Swagger会使用到springfox-swagger,它对Spring和Swagger的使用进行了整合

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>${springfox.swagger.version}</version>
</dependency>
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>${springfox.swagger.version}</version>
</dependency>

二:使用

1、Spring中配置Swagger

/*** Swagger2配置类* 在与spring boot集成时,放在与Application.java同级的目录下。* 或者通过 @Import 导入配置*/
@Configuration
@EnableSwagger2
public class Swagger2 {/*** 创建API应用* apiInfo() 增加API相关信息* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,* 本例采用指定扫描的包路径来定义指定要建立API的目录。* @return*/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.turbo.demo.controller")).paths(PathSelectors.any()).build();}/*** 创建该API的基本信息(这些基本信息会展现在文档页面中)* 访问地址:http://项目实际地址/swagger-ui.html* @return*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Spring Boot中使用Swagger2构建RESTful APIs").description("").termsOfServiceUrl("").contact("zou", "", "zouxq412@foxmail.com").version("1.0").build();}
}

2、API注解

@Api

用在类上,该注解将一个Controller(Class)标注为一个swagger资源(API)。在默认情况下,Swagger-Core只会扫描解析具有@Api注解的类,而会自动忽略其他类别资源(JAX-RS endpoints,Servlets等等)的注解。该注解包含以下几个重要属性

  • tags API分组标签。具有相同标签的API将会被归并在一组内展示。
  • value 如果tags没有定义,value将作为Api的tags使用
  • description API的详细描述,在1.5.X版本之后不再使用,但实际发现在2.0.0版本中仍然可以使用

@ApiOperation

在指定的(路由)路径上,对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有:

  • value 对操作的简单说明,长度为120个字母,60个汉字。
  • notes 对操作的详细说明。
  • httpMethod HTTP请求的动作名,可选值有:"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"。
  • code 默认为200,有效值必须符合标准的HTTP Status Code Definitions。

@ApiImplicitParams

用在方法上,注解ApiImplicitParam的容器类,以数组方式存储。

@ApiImplicitParam

对API的单一参数进行注解。虽然注解@ApiParam同JAX-RS参数相绑定,但这个@ApiImplicitParam注解可以以统一的方式定义参数列表,也是在Servelet及非JAX-RS环境下,唯一的方式参数定义方式。注意这个注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。可以设置以下重要参数属性:

  • name 参数名称
  • value 参数的简短描述
  • required 是否为必传参数
  • dataType 参数类型,可以为类名,也可以为基本类型(String,int、boolean等)
  • paramType 参数的传入(请求)类型,可选的值有path, query, body, header or form。

@ApiParam

增加对参数的元信息说明。这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下。其主要的属性有

  • required 是否为必传参数,默认为false
  • value 参数简短说明

@ApiResponses

注解@ApiResponse的包装类,数组结构。即使需要使用一个@ApiResponse注解,也需要将@ApiResponse注解包含在注解@ApiResponses内。

@ApiResponse

描述一个操作可能的返回结果。当REST API请求发生时,这个注解可用于描述所有可能的成功与错误码。可以用,也可以不用这个注解去描述操作的返回类型,但成功操作的返回类型必须在@ApiOperation中定义。如果API具有不同的返回类型,那么需要分别定义返回值,并将返回类型进行关联。但Swagger不支持同一返回码,多种返回类型的注解。注意:这个注解必须被包含在@ApiResponses注解中。

  • code HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。
  • message 更加易于理解的文本消息
  • response 返回类型信息,必须使用完全限定类名,比如“com.xyz.cc.Person.class”。
  • responseContainer 如果返回类型为容器类型,可以设置相应的值。有效值为 "List", "Set" or "Map",其他任何无效的值都会被忽略。

3、Model注解

对于Model的注解,Swagger提供了两个:@ApiModel及@ApiModelProperty,分别用以描述Model及Model内的属性。

@ApiModel

描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)

提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操作内,所有的类将自动被内省(introspected),但利用这个注解可以做一些更加详细的model结构说明。主要属性有:

  • value model的别名,默认为类名
  • description model的详细描述

@ApiModelProperty

描述一个model的属性

对model属性的注解,主要的属性值有:

  • value 属性简短描述
  • example 属性的示例值
  • required 是否为必须值

4、注解示例

Api 示例

@AllArgsConstructor
@RestController
@RequestMapping("/api/category")
@Api(value = "/category", tags = "组件分类")
public class BizCategoryController {private IBizCategoryService bizCategoryService;@GetMapping("/list")@ApiOperation(value = "列表", notes = "分页列表")public R<PageModel<BizCategory>> list(PageQuery pageQuery,@RequestParam @ApiParam("组件分类名称") String name) {IPage<BizCategory> page = bizCategoryService.page(pageQuery.loadPage(),new LambdaQueryWrapper<BizCategory>().like(BizCategory::getName, name));return R.success(page);}@GetMapping("/list/all")@ApiOperation(value = "查询所有", notes = "分页列表")public R<List<BizCategory>> listAll() {List<BizCategory> categories = bizCategoryService.list();return R.success(categories);}@GetMapping("/{categoryId}")@ApiOperation(value = "详情", notes = "组件分类详情")public R<BizCategory> detail(@PathVariable @ApiParam("分类Id") Long categoryId) {BizCategory category = bizCategoryService.getById(categoryId);return R.success(category);}@PostMapping("/save")@ApiOperation(value = "保存", notes = "新增或修改")@ApiImplicitParams({@ApiImplicitParam(paramType = "form", name = "categoryId", value = "组件id(修改时为必填)"),@ApiImplicitParam(paramType = "form", name = "name", value = "组件分类名称", required = true)})public R<BizCategory> save(Long categoryId, String name) {BizCategory category = new BizCategory();category.setId(categoryId);category.setName(name);bizCategoryService.saveOrUpdate(category);return R.success(category);}@DeleteMapping("/{categoryId}")@ApiOperation(value = "删除", notes = "删除")public R delete(@PathVariable @ApiParam("分类Id") Long categoryId) {bizCategoryService.delete(categoryId);return R.success();}
}

ApiModel 示例

@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
@ApiModel(value="BizComponent对象", description="组件")
public class BizComponent implements Serializable {private static final long serialVersionUID = 1L;@TableId(value = "id", type = IdType.AUTO)private Long id;@ApiModelProperty(value = "分类")private Long categoryId;@ApiModelProperty(value = "组件名称")private String name;@ApiModelProperty(value = "组件描述")private String description;@ApiModelProperty(value = "日期字段")private LocalDateTime componentTime;@ApiModelProperty(value = "创建时间")@TableField(fill = FieldFill.INSERT)private LocalDateTime createTime;@ApiModelProperty(value = "修改时间")@TableField(fill = FieldFill.INSERT_UPDATE)private LocalDateTime modifiedTime;
}

三:swagger-ui界面

swagger生成的api文档信息接口为/v2/api-docs,不过我们可以使用ui界面更加清晰的查看文档说明,并且还能够在线调试

1、springfox-swagger-ui

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>${springfox.swagger.version}</version>
</dependency>

如果是使用springfox-swagger-ui,启动项目后的api文档访问路径是 /swagger-ui.html

 

2、swagger-bootstrap-ui

swagger-bootstrap-ui是springfox-swagger的增强UI实现,我个人更推荐使用这个ui,api文档结构更加清晰,在线调试也很方便

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>${swagger.bootstrap.ui.version}</version>
</dependency>

访问的url为 /doc.html

 

四:Swagger分组

Swagger的分组接口是通过后端配置不同的扫描包,将后端的接口,按配置的扫描包基础属性响应给前端

后端java的配置如下,指定分组名和各自要扫描的包

@Bean(value = "defaultApi")
public Docket defaultApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("默认接口").select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build();
}
@Bean(value = "groupApi")
public Docket groupRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(groupApiInfo()).groupName("分组接口").select().apis(RequestHandlerSelectors.basePackage("com.example.demo.group")).paths(PathSelectors.any()).build();
}

分组信息的接口为 /swagger-resources

[{"name": "分组接口","url": "/v2/api-docs?group=分组接口","swaggerVersion": "2.0","location": "/v2/api-docs?group=分组接口"},{"name": "默认接口","url": "/v2/api-docs?group=默认接口","swaggerVersion": "2.0","location": "/v2/api-docs?group=默认接口"}
]

在swagger-ui中也可以通过分组来查看api文档

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

如若内容造成侵权/违法违规/事实不符,请联系瞎胡闹网进行投诉反馈,一经查实,立即删除!

相关文章

GPU术语

可向量化循环 可向量化循环通常是指在编程中&#xff0c;能够被转换为向量操作或矩阵运算的循环结构。 在传统编程中&#xff0c;对于数组或向量中的每个元素执行相同的操作时&#xff0c;开发者可能会使用for循环逐一进行处理。然而&#xff0c;许多现代编程语言和库提供了向…

在做题中学习(50):搜索插入位置

35. 搜索插入位置 - 力扣&#xff08;LeetCode&#xff09; 解法&#xff1a;二分查找 思路&#xff1a;题目是有序的&#xff0c;时间复杂度O(logN),二分没跑了&#xff0c;题目说如果找不到target&#xff0c;返回它应该被插入位置的下标&#xff0c;所以可以分析一下示例2…

零基础代码随想录【Day27】|| 39. 组合总和,40.组合总和II, 131.分割回文串

目录 DAY27 39. 组合总和 解题思路&代码 40.组合总和II 解题思路&代码 131.分割回文串 解题思路&代码 DAY27 39. 组合总和 力扣题目链接(opens new window) 给定一个无重复元素的数组 candidates 和一个目标数 target &#xff0c;找出 candidates 中所有…

如果你作 为Java程序员曾经遭遇过NullPointerException,请举起手

如果你作 为Java程序员曾经遭遇过NullPointerException&#xff0c;请举起手 1.让Optional发光发热&#xff1a;去除代码中对null的检查&#xff0c; 采用防御式检查减少NullPointerException java8实战 书籍 第225页 免费下载链接&#xff1a; https://pan.quark.cn/s/5cf68…

STM32:配置EXTI—对射式红外传感器计次

文章目录 1、中断1.2 中断系统1.3 中断执行流程 2、STM32中断2.2EXTI&#xff08;外部中断&#xff09;2.3 EXTI 的基本结构2.4 AFIO复用IO口 3、NVIC基本结构3.2 NVIC优先级分组 4、配置EXTI4.2 AFIO 库函数4.3 EXTI 库函数4.4 NVIC 库函数4.5 配置EXTI的步骤4.6 初始化EXTI 1…

自动装车系统中激光雷达如何应对复杂环境

自动装车系统中激光雷达的稳定运行策略 在自动装车系统的设计和实施中&#xff0c;激光雷达作为核心传感器之一&#xff0c;其性能和准确性直接关系到整个系统的稳定性和工作效率。然而&#xff0c;实际运行中的现场环境往往复杂多变&#xff0c;对激光雷达的稳定运行构成一定…

[AI OpenAI-doc] 迁移指南 Beta

我们已经改变了助手 API 在 beta 的 v1 版本和 v2 版本之间工具和文件的工作方式。今天&#xff0c;通过 API&#xff0c;两个 beta 版本仍然可以访问&#xff0c;但我们建议尽快迁移到我们 API 的最新版本。我们将在 2024 年底之前废弃 beta 的 v1 版本。 如果您今天不使用助手…

华人团队用大模型实现“读心术”:大脑活动直接变文字

NeurIPS收录的一项新研究&#xff0c;让大模型也学会“读心术”了&#xff01; 通过学习脑电波数据&#xff0c;模型成功地把受试者的脑电图信号翻译成了文本。 而且整个过程不需要大型设备&#xff0c;只要一块特制的“头巾”就能实现。 这项成果名为DeWave&#xff0c;能在…

鸿蒙内核源码分析(时间管理篇) | 谁是内核基本时间单位

时间概念太重要了&#xff0c;在鸿蒙内核又是如何管理和使用时间的呢? 时间管理以系统时钟 g_sysClock 为基础&#xff0c;给应用程序提供所有和时间有关的服务。 用户以秒、毫秒为单位计时.操作系统以Tick为单位计时&#xff0c;这个认识很重要. 每秒的tick大小很大程度上决…

解决 git克隆拉取代码报SSL certificate problem错误

问题&#xff1a;拉取代码时报错&#xff0c;SSL证书问题:证书链中的自签名证书问题 解决&#xff1a;只需要关闭证书验证&#xff0c;执行下面代码即可&#xff1a; git config --global http.sslVerify "false" 再次拉取代码就可以了

STC89C52驱动XPT2046AD转换

目录 简介封装接线&#xff08;单端&#xff09;时序以及命令字SPI时序命令字 程序XPT2046.CXPT2046.hmain.c测试 简介 XPT2046是一款4线电阻式触摸屏控制器&#xff0c;采用12位125 kHz采样SAR类型A / D转换器。XPT2046工作电压低至2.2V&#xff0c;支持1.5V至VCC的数字I/O接…

暗区突围服务器连接失败/网络异常/无法连接下载解决方法

暗区突围是一款仿真战场的模拟&#xff0c;首要介绍的自然是游戏中基本都会参与的模式&#xff0c;叫做战术行动&#xff0c;大家参与其中是会作为特遣队员的身份来做任务&#xff0c;面临的是一个全面自给自足的战场环境&#xff0c;这种模式要求玩家在进入暗区之前自行筹备所…

Jmeter 中 CSV 如何参数化测试数据并实现自动断言

当我们使用Jmeter工具进行接口测试&#xff0c;可利用CSV Data Set Config配置元件&#xff0c;对测试数据进行参数化&#xff0c;循环读取csv文档中每一行测试用例数据&#xff0c;来实现接口自动化。此种情况下&#xff0c;很多测试工程师只会人工地查看响应结果来判断用例是…

PC小程序解密及反编译

一、小程序包解密 小程序原始加密包位置C:\Users\administrator\Documents\WeChat Files\Applet\wx234324324324 二、wxappUnpacker反编译 npm install./bingo D:\temp\小程序包解密\wxpack\wx234324324324.wxapkg 三、查看反编译后的文件

阿里云国际服(alibabacloud)介绍、注册、购买教程?

一、什么是阿里云国际版&#xff1f; 阿里云分为国内版和国际版。国内版仅面向中国大陆客户&#xff0c;国际版面向全球客户。 二、国际版与国内版有何异同&#xff1f; 1&#xff09;异&#xff1a;除了目标客户不同&#xff0c;运营主体不同&#xff0c;所需遵守的法律与政…

精酿啤酒:种类与风格的多样性探索

啤酒&#xff0c;这一古老的酒精饮品&#xff0c;随着时代的发展与技术的进步&#xff0c;已经衍生出了无数种类与风格。其中&#xff0c;精酿啤酒在近年来备受瞩目&#xff0c;以其与众不同的酿造工艺和风味&#xff0c;成为了啤酒爱好者们的新宠。Fendi club 啤酒&#xff0c…

k8s常见问题:如何处理CrashLoopBackOff问题?

CrashLoopBackOff 概述 首先关于CrashLoopBackOff并不是代表一种错误&#xff0c; "CrashLoopBackOff 是 Kubernetes 中的一个状态&#xff0c;表示在一个 Pod 中发生的重启循环&#xff1a;Pod 中的一个容器启动之后发生了问题&#xff0c;然后反复重启。 Kubernetes 会…

Hive3.0新特性:Materialized Views 物化视图

Materialized Views 物化视图 在 Apache Hive 3.0 中引入了物化视图&#xff08;Materialized Views&#xff09;的支持&#xff0c;它们是预先计算并缓存了查询结果的数据结构&#xff0c;以提高查询性能和降低延迟。物化视图通过将查询的结果存储在物理表中来实现&#xff0…

武汉星起航:五对一服务体系,助力创业者成功进军跨境电商市场

随着全球化的深入发展和互联网的普及&#xff0c;跨境电商已成为越来越多国内创业者的首选。然而&#xff0c;跨境电商市场的复杂性和多变性使得许多新手创业者望而却步。在这样的背景下&#xff0c;武汉星起航电子商务有限公司以其独特的五对一服务体系&#xff0c;为创业者提…

为什么企业高管更偏爱中外合办硕士?人大女王金融硕士为你解析

在当今全球化的商业环境中&#xff0c;企业高管们对于自身的职业发展和知识更新提出了越来越高的要求。这其中&#xff0c;中外合办硕士项目因其独特的优势&#xff0c;逐渐受到了企业高管的青睐。那么&#xff0c;为什么企业高管更偏爱中外合办硕士呢&#xff1f;下面我们以人…