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://www.mzph.cn/web/7018.shtml

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

karateclub，一个超酷的 Python 库！

karateclub，一个超酷的 Python 库！

更多资料获取 &#x1f4da; 个人网站&#xff1a;ipengtao.com 大家好&#xff0c;今天为大家分享一个超酷的 Python 库 - karateclub。 Github地址&#xff1a;https://github.com/benedekrozemberczki/karateclub Python karateclub是一个用于图嵌入和图聚类的库&#xff…
阅读更多...
Springboot+mybatis升级版（Postman测试）

Springboot+mybatis升级版（Postman测试）

一、项目结构 1.导入依赖 <?xml version"1.0" encoding"UTF-8"?> <project xmlns"http://maven.apache.org/POM/4.0.0"xmlns:xsi"http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation"http://maven.apach…
阅读更多...
平面分割--------PCL

平面分割--------PCL

平面分割 bool PclTool::planeSegmentation(pcl::PointCloud<pcl::PointXYZ>::Ptr cloud, pcl::ModelCoefficients::Ptr coefficients, pcl::PointIndices::Ptr inliers) {std::cout << "Point cloud data: " << cloud->points.size() <<…
阅读更多...
8.【Orangepi Zero2】UDEV的配置文件，自动挂载U盘

8.【Orangepi Zero2】UDEV的配置文件，自动挂载U盘

8.UDEV的配置文件&#xff0c;自动挂载U盘 UDEV的配置文件udev 规则的匹配键挂载U盘手动挂载U盘自动挂载usbpan.rules tree命令 UDEV的配置文件 参考文章&#xff1a;Linux 基础 – udev 和 rules 使用规则5 规则文件是 udev 里最重要的部分&#xff0c;默认是存放在 /etc/ud…
阅读更多...
CVE-2019-19945漏洞复现 Openwrt针对uhttpd漏洞利用

CVE-2019-19945漏洞复现 Openwrt针对uhttpd漏洞利用

根据官方漏洞的文档&#xff0c;该漏洞的复现工作我会基于openwrt的18.06.4这个版本进行测试。我选取的环境是渗透测试常用的kali-Linux系统&#xff0c;然后在其中搭建docker环境来完成相应的实验环境的部署。我通过这个核心命令获取docker环境&#xff1a; sudo docker impo…
阅读更多...
微信答题链接怎么做_新手也能快速上手制作

微信答题链接怎么做_新手也能快速上手制作

在数字营销日新月异的今天&#xff0c;如何有效吸引用户参与、提升品牌曝光度&#xff0c;成为了每一个营销人都在思考的问题。而微信答题链接&#xff0c;作为一种新兴的互动营销方式&#xff0c;正以其独特的魅力&#xff0c;在营销界掀起一股新的热潮。今天&#xff0c;就让…
阅读更多...
从C向C++16——常见容器2

从C向C++16——常见容器2

一.stack容器 1.stack理解 概念&#xff1a; stack是一种先进后出的数据结构&#xff0c;它只有一个出口。 它在C中也叫栈&#xff0c;类似于我们在《数据结构和算法》里面的栈&#xff0c;只不过在C中把其封装成库&#xff0c;我们可以直接使用。 注意&#xff1a;栈中只有…
阅读更多...
【精品毕设推荐】搜索引擎的设计与实现

【精品毕设推荐】搜索引擎的设计与实现

点击免费下载原文及代码 摘要 我们处在一个大数据的时代&#xff0c;伴随着网络信息资源的庞大&#xff0c;人们越来越多地注重怎样才能快速有效地从海量的网络信息中&#xff0c;检索出自己需要的、潜在的、有价值的信息&#xff0c;从而可以有效地在日常工作和生活中发挥作…
阅读更多...
【UnityRPG游戏制作】Unity_RPG项目之场景环境搭建和解析

【UnityRPG游戏制作】Unity_RPG项目之场景环境搭建和解析

&#x1f468;‍&#x1f4bb;个人主页&#xff1a;元宇宙-秩沅 &#x1f468;‍&#x1f4bb; hallo 欢迎 点赞&#x1f44d; 收藏⭐ 留言&#x1f4dd; 加关注✅! &#x1f468;‍&#x1f4bb; 本文由 秩沅 原创 &#x1f468;‍&#x1f4bb; 收录于专栏&#xff1a;Uni…
阅读更多...
事件知识图谱 - EventKGE_Event knowledge graph embedding with event causal transfer

事件知识图谱 - EventKGE_Event knowledge graph embedding with event causal transfer

EventKGE: Event knowledge graph embedding with event causal transfer 作者&#xff1a;Daiyi Li&#xff08;南航&#xff09; 来源&#xff1a;2023 Knowledge-Based Systems&#xff08;中科院一区&#xff0c;影响因子8.8&#xff09; 论文&#xff1a;[ScienceDirec…
阅读更多...
Linux中gcc/g++的使用

Linux中gcc/g++的使用

文章目录 前言gcc/g 前言 gcc和g即为编译器。其中gcc为c语言的编译器&#xff0c;只能编译c语言&#xff1b;g为c的编译器&#xff0c;既能编译c语言&#xff0c;又能编译c。 在前面的文章中&#xff0c;我们提到代码转换成可执行程序需要经过 预处理&#xff08;进行宏替换)…
阅读更多...
一、Vagrant搭建相关环境

一、Vagrant搭建相关环境

目录 一、创建Vagrant相关环境1.下载安装VirtualBox2.在BlOS中设置CPU虚拟化3.使用Vagrant新建linux虚拟机3.1下载Vagrant3.2Vagrant官方镜像仓库3.3使用Vagrant初始化一个centos7的虚拟机 4.设置固定ip地址 二、安装docker1.按照docker 三、docker安装一些中间件1.mysql安装2.…
阅读更多...
从零开始学AI绘画，万字Stable Diffusion终极教程（六）

从零开始学AI绘画，万字Stable Diffusion终极教程（六）

【第6期】知识补充 欢迎来到SD的终极教程&#xff0c;这是我们的第六节课&#xff0c;也是最后一节课 这套课程分为六节课&#xff0c;会系统性的介绍sd的全部功能&#xff0c;让你打下坚实牢靠的基础 1.SD入门 2.关键词 3.Lora模型 4.图生图 5.controlnet 6.知识补充 …
阅读更多...
Linux环境创建普通用户，授权root权限。报错:usermod: group ‘sudo‘ does not exist

Linux环境创建普通用户，授权root权限。报错:usermod: group ‘sudo‘ does not exist

在Linux环境下&#xff0c;创建普通用户并授权root权限需要以下步骤&#xff1a; 1. 以root用户登录终端。 2. 执行以下命令创建一个新的用户&#xff0c;其中username为你想要创建的用户名&#xff0c;可根据实际情况自行更改。 adduser username 3. 设置该用户的密码&…
阅读更多...
【C++】vector类的增删改查模拟实现（图例超详细解析！！！）

【C++】vector类的增删改查模拟实现（图例超详细解析！！！）

目录 一、前言 二、源码引入 三、vector的模拟实现 ✨实现框架 ✨前情提要 ✨Member functions —— 成员函数 ⚡构造函数 ⭐无参构造 ⭐迭代器区间构造 ⭐n个值构造 ⚡拷贝构造 ⚡运算符赋值重载 ⚡析构函数 ✨Element access —— 元素访问 ⚡operator[ ] …
阅读更多...
VsCode插件 -- Power Mode

VsCode插件 -- Power Mode

一、安装插件 1. 首先在扩展市场里搜索 Power Mode 插件&#xff0c;如下图 二、配置插件 设置 点击小齿轮 打上勾 就可以了 第二种设置方法 1. 安装完成之后&#xff0c;使用快捷键 Ctrl Shift P 打开命令面板&#xff0c;在命令行中输入 settings.json &#xff0c; 选择首…
阅读更多...
通过maven命令行mvn的方式，下载依赖jar包

通过maven命令行mvn的方式，下载依赖jar包

目录 目标步骤执行mvn命令 目标 有时通过idea-maven-reload all maven projects更新项目依赖时&#xff0c;会报错Could not find artifact xxx.xx:xxx.x:xxx.jar (https://repo1.maven.org/maven2/org/)。 此时可尝试通过mvn命令行进行依赖下载&#xff08;需要配置maven本地…
阅读更多...
【Python深度学习（第二版）（2）】深度学习之前：机器学习简史

【Python深度学习（第二版）（2）】深度学习之前：机器学习简史

文章目录 一. 深度学习的起源1. 概率建模--机器学习分类器2. 早期神经网络--反向传播算法的转折3. 核方法 -- 忽略神经网络4. 决策树、随机森林和梯度提升机5. 神经网络替代svm与决策树 二. 深度学习与机器学习有何不同 可以这样说&#xff0c;当前工业界所使用的大部分机器学习…
阅读更多...
asp.net朱勇项目个人博客(3)

asp.net朱勇项目个人博客(3)

引文:按照书上的项目&#xff0c;我们最后实现管理端的三个增删改查的功能即可,相对与三个增删改查&#xff0c;文章&#xff0c;分类和留言&#xff0c;这里我们所需要用的的关联的一个表就是文章表&#xff0c;因为文章表每一个文章的增加显示和修改都需要对应的一个分类&…
阅读更多...
【Linux】网络连接配置——nmcli工具配置连接增删改查实例

【Linux】网络连接配置——nmcli工具配置连接增删改查实例

nmcli工具配置连接增删改查实例 &#xff08;一&#xff09;网络连接配置基本项目1.网络接口配置2.主机名配置3.DNS服务器配置 &#xff08;二&#xff09;网络连接配置文件&#xff08;三&#xff09;网络配置方法&#xff08;四&#xff09;nmcli工具配置连接管理1.增2.查3.改…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023