【Spring Boot】构建RESTful服务 — 使用Swagger生成Web API文档
使用Swagger生成Web API文档
高质量的API文档在系统开发的过程中非常重要。本节介绍什么是Swagger,如何在Spring Boot项目中集成Swagger构建RESTful API文档,以及为Swagger配置Token等通用参数。
1.什么是Swagger
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTful风格的Web服务,是非常流行的API表达工具。
普通的API文档存在以下问题:
1)由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),创建这样一份高质量的文档是一件非常烦琐的工作。
2)随着需求的不断变化,接口文档必须同步修改,就很容易出现文档和业务不一致的情况。为了解决这些问题,Swagger应运而生,它能够自动生成完善的RESTful API文档,并根据后台代码的修改同步更新。这样既可以减少维护接口文档的工作量,又能将说明内容集成到实现代码中,让维护文档和修改代码合为一体,实现代码逻辑与说明文档的同步更新。另外,Swagger也提供了完整的测试页面来调试API,让API测试变得轻松、简单。
2.使用Swagger生成Web API文档
在Spring Boot项目中集成Swagger同样非常简单,只需在项目中引入springfox-swagger2和springfox-swagger-ui依赖即可。下面就以之前的用户管理模块接口为例来感受Swagger的魅力。
步骤01 配置Swagger的依赖。
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>3.0.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>3.0.0</version></dependency>
在上面的示例中,在项目pom.xml配置文件中引入了springfox-swagger2和springfox-swagger-ui两个依赖包。其中swagger2是主要的文档生成组件,swagger-ui为页面显示组件。
步骤02 创建Swagger2配置类。
@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {@Beanpublic Docket createRestApi () {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Spring boot中使用Swagger2构建RESTful APIs").description("相关文章请关注:https://blog.csdn.net/weixin_45627039?spm=1000.2115.3001.5343").termsOfServiceUrl("https://blog.csdn.net/weixin_45627039?spm=1000.2115.3001.5343")// .contact("架构师精进").version("1.0").build();}/*** swagger增加url映射* @param registry*/@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars");}
}
在上面的示例中,我们在SwaggerConfig的类上添加了@Configuration和@EnableSwagger2两个注解。
@Configuration注解让Spring Boot来加载该类配置。
@EnableSwagger2注解启用Swagger2,通过配置一个Docket Bean,来配置映射路径和要扫描的接口所在的位置。
apiInfo主要配置Swagger2文档网站的信息,比如网站的标题、网站的描述、使用的协议等。
需要注意的是:
1)basePackage可以在SwaggerConfig中配置com.weiz.example01.controller,也可以在启动器ComponentScan中配置。
2)需要在SwaggerConfig中配置Swagger的URL映射地址:/swagger-ui.html。
步骤03 添加文档说明内容。
上面的配置完成之后,接下来需要在API上增加内容说明。我们直接在之前的用户管理模块的UserController中增加相应的接口内容说明,代码如下:
@Api(tags = {"用户接口"})@RestControllerpublic class UserController {@ApiOperation(value="创建用户", notes="根据User对象创建用户")@PostMapping(value ="user")public JSONResult save(@RequestBody User user){System.out.println("用户创建成功:" + user.getName());return JSONResult.ok(201, "用户创建成功");}@ApiOperation(value="更新用户详细信息", notes="根据id来指定更新对象,并根据传过来的user信息来更新用户详细信息")@PutMapping(value = "user")public JSONResult update(@RequestBody User user) {System.out.println("用户修改成功:" + user.getName());return JSONResult.ok(203, "用户修改成功");}@ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")@ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType ="Long", paramType = "query")@DeleteMapping("user/{userId}")public JSONResult delete(@PathVariable String userId) {System.out.println("用户删除成功:" + userId);return JSONResult.ok(204,"用户删除成功");}}
在上面的示例中,主要为UserController中的接口增加了接口信息描述,包括接口的用途、请求参数说明等。
1)@Api注解:用来给整个控制器(Controller)增加说明。
2)@ApiOperation注解:用来给各个API方法增加说明。
3)@ApiImplicitParams、@ApiImplicitParam注解:用来给参数增加说明。
步骤04 查看生成的API文档。
完成上面的配置和代码修改之后,Swagger 2就集成到Spring Boot项目中了。接下来启动项目,在浏览器中访问http://localhost:8080/swagger-ui.html,Swagger会自动构建接口说明文档,如图所示。

Swagger自动将用户管理模块的全部接口信息展现出来,包括接口功能说明、调用方式、请求参数、返回数据结构等信息。
在Swagger页面上,我们发现每个接口描述右侧都有一个按钮try it out,单击try it out按钮即可调用该接口进行测试。如图所示,在获取人员信息的接口上单击try it out按钮,输入userId的请求参数“2001”,单击Execute按钮就会将请求发送到后台,从而进行接口验证测试。

3.为Swagger添加token参数
很多时候,客户端在调用API时需要在HTTP的请求头携带通用参数,比如权限验证的token参数等。但是Swagger是怎么描述此类参数的呢?接下来通过示例演示如何为Swagger添加固定的请求参数。
其实非常简单,修改Swagger2Config配置类,利用ParameterBuilder构成请求参数。具体示例代码如下:
@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {@Beanpublic Docket createRestApi() {ParameterBuilder parameterBuilder = new ParameterBuilder();List<Parameter> parameters = new ArrayList<Parameter>();parameterBuilder.name("token").description("token令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any()).build().globalOperationParameters(parameters);}...
}
在上面的示例中,通过ParameterBuilder类把token作为全局统一的参数添加到HTTP的请求头中。系统所有的API都会统一加上此参数。
完成之后重新启动应用,再次查看接口,如图所示,我们可以看到接口参数中已经支持发送token请求参数。

人员管理模块中的所有API都统一加上了token参数,调用时Swagger会将token参数自动加入HTTP的请求头。
4.Swagger常用注解
Swagger提供了一系列注解来描述接口信息,包括接口说明、请求方法、请求参数、返回信息等,常用注解如表所示。

在实际项目中,Swagger除了提供@ApiImplicitParams注解描述简单的参数之外,还提供了用于对象参数的@ApiModel和@ApiModelProperty两个注解,用于封装的对象作为传入参数或返回数据。
@ApiModel负责描述对象的信息
@ApiModelProperty负责描述对象中属性的相关内容
以上是在项目中常用的一些注解,利用这些注解就可以构建出清晰的API文档。
相关文章:
【Spring Boot】构建RESTful服务 — 使用Swagger生成Web API文档
使用Swagger生成Web API文档 高质量的API文档在系统开发的过程中非常重要。本节介绍什么是Swagger,如何在Spring Boot项目中集成Swagger构建RESTful API文档,以及为Swagger配置Token等通用参数。 1.什么是Swagger Swagger是一个规范和完整的框架&…...
【实战】 九、深入React 状态管理与Redux机制(五) —— React17+React Hook+TS4 最佳实践,仿 Jira 企业级项目(二十)
文章目录 一、项目起航:项目初始化与配置二、React 与 Hook 应用:实现项目列表三、TS 应用:JS神助攻 - 强类型四、JWT、用户认证与异步请求五、CSS 其实很简单 - 用 CSS-in-JS 添加样式六、用户体验优化 - 加载中和错误状态处理七、Hook&…...
PHP傻瓜也能搭建自己框架
PHP最简单自定义自己的框架(一) PHP最简单自定义自己的框架创建目录结构(二) PHP最简单自定义自己的框架定义常量自动生成目录(三) PHP最简单自定义自己的框架控制器自动加载运行(四…...
为什么商业基础软件需要开源
Bytebase 本身是一家商业软件公司,而作为最核心资产的代码从 Day 0 却是开源的。同时我们还是 star-history.com 的运营者,大家在各种开源渠道会看到它生成的图: 一直以来,常会被别人问起的一个问题,就是为什么 Byteba…...
【自用】云服务器 使用 docker 搭建 HomeAssistant + MQTT 物联网平台
总览 1.搭建流程概述 2.准备工作 3.开始搭建! 4.总结 如果想看 ESP32 或其他使用 MicroPython 编程的单片机如何连接到该云服务器,实现 HomeAssistant 控制 单片机的内容,请看我这篇博客的下一篇。 一、搭建流程概述 0.总体流程 我们需要…...
ABAP: SQL 多值查询
基础查数据 问题举例:例如查物料类型为ZFRT、ZROH和ZRSA的物料编码。 1、直接查询,三种不同类型的物料类型是或的关系。 SELECT DISTINCT ma~matnr ma~mtartFROM mara AS maINNER JOIN mbewh AS mbON ma~matnr mb~matnrINTO CORRESPONDING FIELDS OF…...
分布式学习最佳实践:从分布式系统的特征开始
正文 在延伸feature(分布式系统需要考虑的特性)的时候,我逐渐明白,这是因为要满足这些feature,才设计了很多协议与算法,也提出了一些理论。比如说,这是因为要解决去中心化副本的一致性问题&…...
第三章 图论 No.8最近公共祖先lca, tarjan与次小生成树
文章目录 lcaTarjan板子题:1172. 祖孙询问lca或tarjan:1171. 距离356. 次小生成树352. 闇の連鎖 lca O ( m l o g n ) O(mlogn) O(mlogn),n为节点数量,m为询问次数,lca是一种在线处理询问的算法 自己也是自己的祖先 倍…...
[Kubernetes]Kubeflow Pipelines - 基本介绍与安装方法
1. 背景 近些年来,人工智能技术在自然语言处理、视觉图像和自动驾驶方面都取得不小的成就,无论是工业界还是学术界大家都在惊叹一个又一个的模型设计。但是对于真正做过算法工程落地的同学,在惊叹这些模型的同时,更多的是在忧虑如…...
Sui网络的稳定性和高性能
Sui的最初的协议开发者设计了可扩展的网络,通过水平扩展的方式来保持可负担得起的gas费用。其他区块链与之相比,则使用稀缺性和交易成本来控制网络活动。 Sui主网上线前90天的数据指标证明了这一设计概念,在保持100%正常运行的同…...
RabbitMQ 安装教程
RabbitMQ 安装教程 特殊说明 因为RabbitMQ基于Erlang开发,所以安装时需要先安装Erlang RabbitMQ和Erlang版本对应关系 查看地址:www.rabbitmq.com/which-erlan… 环境选择 Erlang: 23.3及以上 RabbitMQ: 3.10.1Windows 安装 1. 安装Erlang 下载地…...
STM32F429IGT6使用CubeMX配置GPIO点亮LED灯
1、硬件电路 2、设置RCC,选择高速外部时钟HSE,时钟设置为180MHz 3、配置GPIO引脚 4、生成工程配置 5、部分代码 6、实验现象...
DOM的节点操作+事件高级+DOM事件流+事件对象
一.节点操作 1.父节点: node.parentNode 得到的是离元素最近的父级节点 2.子节点: parentNode.childNodes 所有的子节点 包含元素节点 文本节点等等parentNode.children (非标准) 获取所有的子元素节点,实际开发常用 parentNode.firstChild 获取…...
云端剪切板,让你的数据同步无界
云端剪切板,让你的数据同步无界! 每个人都应该保护自己的数据,同时使它易于访问和共享。这就是我们的云剪切板网站诞生的原因!无论你在哪里,只要登录我们的网站,就可以随时随地使用你的剪切板数据。 你可…...
Location匹配与Rewrite重写
一、常见的Nginx正则表达式 ^ :匹配输入字符串的起始位置 $ :匹配输入字符串的结束位置 * :匹配前面的字符零次或多次。如“ol*”能匹配“o”及“ol”、“oll”:匹配前面的字符一次或多次。如“ol”能匹配“ol”及“oll”、“oll…...
Docker源码阅读 - goland环境准备
docker 源码分为两部分 cli 和 moby(docker) tips: docker是从moby拷贝过去的;docker整体是一个C-S架构,cli客户端,docker服务端 docker-ce:https://github.com/docker/docker-ce cli:https://…...
数据库信息速递 -- MariaDB 裁员后,前景不确定 (翻译)
开头还是介绍一下群,如果感兴趣polardb ,mongodb ,mysql ,postgresql ,redis 等有问题,有需求都可以加群群内有各大数据库行业大咖,CTO,可以解决你的问题。加群请加 liuaustin3微信号 ,在新加的朋友会分到3群ÿ…...
4.1 Windows终端安全
数据参考:CISP官方 目录 安全安装保护账户安全本地安全策略安全中心系统服务安全其他安全设置软件安全获取 一、安全安装(以安装windows系统为例) 选择合适的版本 商业版本:家庭版、专业版、专业工作站版、企业版特殊版本&…...
win10强制卸载奇安信天擎
1、win r 打开运行 2、输入msconfig进入系统配置面板 3、点击引导,修改安全引导配置项 4、重启系统(桌面会变成纯黑背景,符合预期,莫紧张) 5、删除安装的文件夹 若是安装天擎时选择的自定义安装,则配置…...
npm常用命令
npm -v:查看 npm 版本 npm init:初始化后会出现一个 Package.json 配置文件,可以在后面加上 -y,快速跳到问答界面 npm install:会根据项目中的 package.json 文件自动给下载项目中所需的全部依赖 npm insall 包含 -…...
AI Agent与Agentic AI:原理、应用、挑战与未来展望
文章目录 一、引言二、AI Agent与Agentic AI的兴起2.1 技术契机与生态成熟2.2 Agent的定义与特征2.3 Agent的发展历程 三、AI Agent的核心技术栈解密3.1 感知模块代码示例:使用Python和OpenCV进行图像识别 3.2 认知与决策模块代码示例:使用OpenAI GPT-3进…...
解决Ubuntu22.04 VMware失败的问题 ubuntu入门之二十八
现象1 打开VMware失败 Ubuntu升级之后打开VMware上报需要安装vmmon和vmnet,点击确认后如下提示 最终上报fail 解决方法 内核升级导致,需要在新内核下重新下载编译安装 查看版本 $ vmware -v VMware Workstation 17.5.1 build-23298084$ lsb_release…...
Psychopy音频的使用
Psychopy音频的使用 本文主要解决以下问题: 指定音频引擎与设备;播放音频文件 本文所使用的环境: Python3.10 numpy2.2.6 psychopy2025.1.1 psychtoolbox3.0.19.14 一、音频配置 Psychopy文档链接为Sound - for audio playback — Psy…...
c#开发AI模型对话
AI模型 前面已经介绍了一般AI模型本地部署,直接调用现成的模型数据。这里主要讲述讲接口集成到我们自己的程序中使用方式。 微软提供了ML.NET来开发和使用AI模型,但是目前国内可能使用不多,至少实践例子很少看见。开发训练模型就不介绍了&am…...
全志A40i android7.1 调试信息打印串口由uart0改为uart3
一,概述 1. 目的 将调试信息打印串口由uart0改为uart3。 2. 版本信息 Uboot版本:2014.07; Kernel版本:Linux-3.10; 二,Uboot 1. sys_config.fex改动 使能uart3(TX:PH00 RX:PH01),并让boo…...
HDFS分布式存储 zookeeper
hadoop介绍 狭义上hadoop是指apache的一款开源软件 用java语言实现开源框架,允许使用简单的变成模型跨计算机对大型集群进行分布式处理(1.海量的数据存储 2.海量数据的计算)Hadoop核心组件 hdfs(分布式文件存储系统)&a…...
为什么要创建 Vue 实例
核心原因:Vue 需要一个「控制中心」来驱动整个应用 你可以把 Vue 实例想象成你应用的**「大脑」或「引擎」。它负责协调模板、数据、逻辑和行为,将它们变成一个活的、可交互的应用**。没有这个实例,你的代码只是一堆静态的 HTML、JavaScript 变量和函数,无法「活」起来。 …...
Scrapy-Redis分布式爬虫架构的可扩展性与容错性增强:基于微服务与容器化的解决方案
在大数据时代,海量数据的采集与处理成为企业和研究机构获取信息的关键环节。Scrapy-Redis作为一种经典的分布式爬虫架构,在处理大规模数据抓取任务时展现出强大的能力。然而,随着业务规模的不断扩大和数据抓取需求的日益复杂,传统…...
SQL Server 触发器调用存储过程实现发送 HTTP 请求
文章目录 需求分析解决第 1 步:前置条件,启用 OLE 自动化方式 1:使用 SQL 实现启用 OLE 自动化方式 2:Sql Server 2005启动OLE自动化方式 3:Sql Server 2008启动OLE自动化第 2 步:创建存储过程第 3 步:创建触发器扩展 - 如何调试?第 1 步:登录 SQL Server 2008第 2 步…...
ubuntu22.04有线网络无法连接,图标也没了
今天突然无法有线网络无法连接任何设备,并且图标都没了 错误案例 往上一顿搜索,试了很多博客都不行,比如 Ubuntu22.04右上角网络图标消失 最后解决的办法 下载网卡驱动,重新安装 操作步骤 查看自己网卡的型号 lspci | gre…...
