【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智能安防平台
前言: 通过AI视觉技术,为船厂提供全面的安全监控解决方案,涵盖交通违规检测、起重机轨道安全、非法入侵检测、盗窃防范、安全规范执行监控等多个方面,能够实现对应负责人反馈机制,并最终实现数据的统计报表。提升船厂…...
抖音增长新引擎:品融电商,一站式全案代运营领跑者
抖音增长新引擎:品融电商,一站式全案代运营领跑者 在抖音这个日活超7亿的流量汪洋中,品牌如何破浪前行?自建团队成本高、效果难控;碎片化运营又难成合力——这正是许多企业面临的增长困局。品融电商以「抖音全案代运营…...
微服务商城-商品微服务
数据表 CREATE TABLE product (id bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT COMMENT 商品id,cateid smallint(6) UNSIGNED NOT NULL DEFAULT 0 COMMENT 类别Id,name varchar(100) NOT NULL DEFAULT COMMENT 商品名称,subtitle varchar(200) NOT NULL DEFAULT COMMENT 商…...
PL0语法,分析器实现!
简介 PL/0 是一种简单的编程语言,通常用于教学编译原理。它的语法结构清晰,功能包括常量定义、变量声明、过程(子程序)定义以及基本的控制结构(如条件语句和循环语句)。 PL/0 语法规范 PL/0 是一种教学用的小型编程语言,由 Niklaus Wirth 设计,用于展示编译原理的核…...
Spring Boot+Neo4j知识图谱实战:3步搭建智能关系网络!
一、引言 在数据驱动的背景下,知识图谱凭借其高效的信息组织能力,正逐步成为各行业应用的关键技术。本文聚焦 Spring Boot与Neo4j图数据库的技术结合,探讨知识图谱开发的实现细节,帮助读者掌握该技术栈在实际项目中的落地方法。 …...
C# SqlSugar:依赖注入与仓储模式实践
C# SqlSugar:依赖注入与仓储模式实践 在 C# 的应用开发中,数据库操作是必不可少的环节。为了让数据访问层更加简洁、高效且易于维护,许多开发者会选择成熟的 ORM(对象关系映射)框架,SqlSugar 就是其中备受…...
用docker来安装部署freeswitch记录
今天刚才测试一个callcenter的项目,所以尝试安装freeswitch 1、使用轩辕镜像 - 中国开发者首选的专业 Docker 镜像加速服务平台 编辑下面/etc/docker/daemon.json文件为 {"registry-mirrors": ["https://docker.xuanyuan.me"] }同时可以进入轩…...
AGain DB和倍数增益的关系
我在设置一款索尼CMOS芯片时,Again增益0db变化为6DB,画面的变化只有2倍DN的增益,比如10变为20。 这与dB和线性增益的关系以及传感器处理流程有关。以下是具体原因分析: 1. dB与线性增益的换算关系 6dB对应的理论线性增益应为&…...
Linux 中如何提取压缩文件 ?
Linux 是一种流行的开源操作系统,它提供了许多工具来管理、压缩和解压缩文件。压缩文件有助于节省存储空间,使数据传输更快。本指南将向您展示如何在 Linux 中提取不同类型的压缩文件。 1. Unpacking ZIP Files ZIP 文件是非常常见的,要在 …...
Webpack性能优化:构建速度与体积优化策略
一、构建速度优化 1、升级Webpack和Node.js 优化效果:Webpack 4比Webpack 3构建时间降低60%-98%。原因: V8引擎优化(for of替代forEach、Map/Set替代Object)。默认使用更快的md4哈希算法。AST直接从Loa…...
