一起来学 SpringBoot 2.x | 第十一篇:集成 Swagger 在线调试

Springboot集成Swagger和Springdoc详解 Swagger2可以让开发者更方便地构建 API 文档和测试,目前最新的Swagger2只支持到3.0.0已经不在维护了,相对应Springboot版本为2.x。针对Springboot2.7.0~2.7.18可以集成swagger2:2.9.2稳定版本,Springboot3.x社区推荐使用 Springdoc OpenAPI 作为其替代品,Springdoc OpenAPI 是 Springfox 的官方继承者,提供了更新的特性和更好的维护。 阅读详情

点击上方“芋道源码”,选择“置顶公众号”

技术文章第一时间送达!

源码精品专栏

 

来源:http://t.cn/EwMgr3F


文档工具导入依赖属性配置实体类restful 风格接口主函数测试总结说点什么


SpringBoot 是为了简化 Spring 应用的创建、运行、调试、部署等一系列问题而诞生的产物,自动装配的特性让我们可以更好的关注业务本身而不是外部的XML配置,我们只需遵循规范,引入相关的依赖就可以轻易的搭建出一个 WEB 工程

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、前后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。

前端和后端唯一联系,变成了API接口;API文档自然就成了前后端开发人员联系的纽带,变得尤为的重要,swagger就是一款让你更好的书写API文档的框架。

文档工具

没有API文档工具之前,基本都是手写API文档的,如有在Word上写的,有在对应的项目目录下readme.md上写的,每个公司都有每个公司的玩法,无所谓好坏。但是这种手写文档带来的弊端就是维护起来苦不堪言,对于接口容易发生变化的开发者来说,维护文档就是噩梦….

好在现如今市场上书写API文档的工具有很多,常见的有 postman、yapi、阿里的RAP 但是能称之为框架的,估计也只有swagger了。

swagger 优缺点

  • 集成方便,功能强大

  • 在线调试与文档生成

  • 代码耦合,需要注解支持,但不影响程序性能

导入依赖

在 pom.xml 中添加 swagger-spring-boot-starter 的依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>com.battcn</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.4.5-RELEASE</version>
</dependency>

属性配置

配置spring.swagger.enabled开启swagger的使用,如果在生产环境中不想用可以在对应的profile下面将它设置为spring.swagger.enabled=false,这样一来接口就不存在暴露的风险

# 扫描的包路径,默认扫描所有
spring.swagger.base-package=com.battcn
# 默认为 true
spring.swagger.enabled=true
更多属性

实体类

swagger 提供了非常齐全的注解,为POJO提供了@ApiModel、@ApiModelProperty,以便更好的渲染最终结果

package com.battcn.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;

/**
 * @author Levin
 * @since 2018/5/10 0007
 */
@ApiModel
public class User implements Serializable {

    private static final long serialVersionUID = 8655851615465363473L;

    private Long id;
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

    // TODO  省略get set
}

restful 风格接口

注解描述

  • @Api: 描述Controller

  • @ApiIgnore: 忽略该Controller,指不对当前类做扫描

  • @ApiOperation: 描述Controller类中的method接口

  • @ApiParam: 单个参数描述,与@ApiImplicitParam不同的是,他是写在参数左侧的。如(@ApiParam(name = "username",value = "用户名") String username)

  • @ApiModel: 描述POJO对象

  • @ApiProperty: 描述POJO对象中的属性值

  • @ApiImplicitParam: 描述单个入参信息

  • @ApiImplicitParams: 描述多个入参信息

  • @ApiResponse: 描述单个出参信息

  • @ApiResponses: 描述多个出参信息

  • @ApiError: 接口错误所返回的信息

package com.battcn.controller;

import com.battcn.entity.User;
import com.battcn.swagger.properties.ApiDataType;
import com.battcn.swagger.properties.ApiParamType;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;

/**
 * swagger
 *
 * @author Levin
 * @since 2018/5/16 0016
 */
@RestController
@RequestMapping("/users")
@Api(tags = "1.1", description = "用户管理", value = "用户管理")
public class UserController {

    private static final Logger log = LoggerFactory.getLogger(UserController.class);

    @GetMapping
    @ApiOperation(value = "条件查询(DONE)")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", dataType = ApiDataType.STRING, paramType = ApiParamType.QUERY),
            @ApiImplicitParam(name = "password", value = "密码", dataType = ApiDataType.STRING, paramType = ApiParamType.QUERY),
    })
    public User query(String username, String password) {
        log.info("多个参数用  @ApiImplicitParams");
        return new User(1L, username, password);
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "主键查询(DONE)")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户编号", dataType = ApiDataType.LONG, paramType = ApiParamType.PATH),
    })
    public User get(@PathVariable Long id) {
        log.info("单个参数用  @ApiImplicitParam");
        return new User(id, "u1", "p1");
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户(DONE)")
    @ApiImplicitParam(name = "id", value = "用户编号", dataType = ApiDataType.LONG, paramType = ApiParamType.PATH)
    public void delete(@PathVariable Long id) {
        log.info("单个参数用 ApiImplicitParam");
    }

    @PostMapping
    @ApiOperation(value = "添加用户(DONE)")
    public User post(@RequestBody User user) {
        log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam");
        return user;
    }

    @PutMapping("/{id}")
    @ApiOperation(value = "修改用户(DONE)")
    public void put(@PathVariable Long id, @RequestBody User user) {
        log.info("如果你不想写 @ApiImplicitParam 那么 swagger 也会使用默认的参数名作为描述信息 ");
    }
}

主函数

添加 @EnableSwagger2Doc 即可

package com.battcn;

import com.battcn.swagger.annotation.EnableSwagger2Doc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * @author Levin
 */
@EnableSwagger2Doc
@SpringBootApplication
public class Chapter10Application {

    public static void main(String[] args) {
        SpringApplication.run(Chapter10Application.class, args);
    }
}

测试

由于上面的接口是 restful 风格的接口,添加和修改无法通过浏览器完成,以前都是自己编写junit或者使用postman之类的工具。现在只需要打开浏览器输入 http://localhost:8080/swagger-ui.html,更多操作请自行体验…

渲染效果

总结

目前很多大佬都写过关于 SpringBoot 的教程了,如有雷同,请多多包涵,本教程基于最新的 spring-boot-starter-parent:2.0.2.RELEASE编写,包括新版本的特性都会一起介绍…

说点什么

全文代码:https://github.com/battcn/spring-boot2-learning/tree/master/chapter10



欢迎加入我的知识星球,一起探讨架构,交流源码。加入方式,长按下方二维码噢:

已在知识星球更新源码解析如下:

  • 《精尽 Dubbo 源码解析系列》69 篇。

  • 《精尽 Netty 源码解析系列》61 篇。

  • 《精尽 Spring 源码解析系列》35 篇。

  • 《精尽 MyBatis 源码解析系列》34 篇。

  • 《数据库实体设计》17 篇。

  • 正在准备更新《精尽 Spring MVC 源码解析系列》

目前在知识星球更新了《Dubbo 源码解析》目录如下:

01. 调试环境搭建
02. 项目结构一览
03. 配置 Configuration
04. 核心流程一览

05. 拓展机制 SPI

06. 线程池

07. 服务暴露 Export

08. 服务引用 Refer

09. 注册中心 Registry

10. 动态编译 Compile

11. 动态代理 Proxy

12. 服务调用 Invoke

13. 调用特性 

14. 过滤器 Filter

15. NIO 服务器

16. P2P 服务器

17. HTTP 服务器

18. 序列化 Serialization

19. 集群容错 Cluster

20. 优雅停机

21. 日志适配

22. 状态检查

23. 监控中心 Monitor

24. 管理中心 Admin

25. 运维命令 QOS

26. 链路追踪 Tracing

... 一共 69+ 篇

目前在知识星球更新了《Netty 源码解析》目录如下:

01. 调试环境搭建
02. NIO 基础
03. Netty 简介
04. 启动 Bootstrap

05. 事件轮询 EventLoop

06. 通道管道 ChannelPipeline

07. 通道 Channel

08. 字节缓冲区 ByteBuf

09. 通道处理器 ChannelHandler

10. 编解码 Codec

11. 工具类 Util

... 一共 61+ 篇

目前在知识星球更新了《数据库实体设计》目录如下:

01. 商品模块
02. 交易模块
03. 营销模块
04. 公用模块

... 一共 17+ 篇

目前在知识星球更新了《Spring 源码解析》目录如下:

01. 调试环境搭建
02. IoC Resource 定位
03. IoC BeanDefinition 载入

04. IoC BeanDefinition 注册

05. IoC Bean 获取

06. IoC Bean 生命周期

... 一共 35+ 篇

目前在知识星球更新了《MyBatis 源码解析》目录如下:

01. 调试环境搭建
02. 项目结构一览
03. MyBatis 面试题合集

04. MyBatis 学习资料合集

05. MyBatis 初始化

06. SQL 初始化

07. SQL 执行

08. 插件体系

09. Spring 集成

... 一共 34+ 篇

源码不易↓↓↓↓↓

点赞支持老艿艿↓↓

Swagger快速入门 官网:https://swagger.io/Swagger 是一个规范和完整的Web API框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。功能主要包含以下几点:A. 使得前后端分离开发更加方便,有利于团队协作;B. 接口文档在线自动生成,降低后端开发人员编写接口文档的负担;C. 接口功能测试;使用Swagger只需要按照它的规范去定义接口及接口相关的信息,再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,以及在线接口调试页面等等; 阅读详情

相关推荐

芋道框架万字详解(前后端分离)、若依框架、yudao-cloud保姆级攻略

芋道开发框架,低代码平台

争者留其名 2万+

芋道 Spring Boot API 接口文档 Swagger 入门

点击上方“芋道源码”,选择“设为星标”做积极的人,而不是积极废人!源码精品专栏原创 | Java 2020 超神之路,很肝~中文详细注释的开源项目RPC 框架 Dubbo 源码解析网络...

芋艿V 3408

SpringBoot集成Swagger2实现API文档自动化实例详解

在现代微服务架构开发中,API文档的自动化生成与维护已成为提升团队协作效率和降低沟通成本的关键环节。Spring Boot作为Java生态中最主流的快速开发框架,其简洁高效的特性深受开发者青睐;而Swagger2则是一款功能强大的API文档生成工具,能够实现接口定义、文档展示与在线测试一体化。本章系统阐述了Spring Boot与Swagger2整合的核心价值,深入剖析为何选择Swagger2作为RESTful API的文档解决方案,并介绍其在前后端分离架构中的关键作用。

weixin_34456923的博客 893

ruoyi-pro 代码生成api,swagger扫描不到

解决ruoyi-pro 代码生成后的api 在swagger-ui中未扫描到的问题。 背景:代码生成新的maven工程目录,目录下的接口不能被swagger扫描到。 解决方法: 1、将新创建的maven工程,加入到启动工程中,加载新创建的maven工程。 2、新增swagger配置类

噗嗤 2923

DDR5内存调优实战:手把手教你搞定Write Leveling Training Mode(附时序图解析)

本文深入解析DDR5内存调优中的Write Leveling Training Mode技术,详细介绍了其核心原理、硬件准备、实战步骤及常见问题解决方案。通过JESD79-5标准定义的反馈机制,帮助硬件工程师精确对齐DQS与CK信号,提升系统稳定性和数据可靠性。附有时序图解析和代码示例,适合DDR5内存系统设计与调试参考。

weixin_29256771的博客 552

【Collibra 驱动 IPD 数据血缘治理】:三层图谱分层展示体系与全链路追踪的技术业务实践

(应用级/数据级/字段级)是理解复杂数据流动的核心手段。其价值不仅体现在可视化的直观性,更在于通过。技术保障血缘不可篡改性,进一步提升IPD数据治理的可靠性。,解决了跨层级血缘分析的性能与可用性矛盾。数据血缘图谱要素定义(字节跳动/腾讯云/信安标委)实现对IPD数据的精准追踪,而数据血缘图谱的。分层交互设计标准(智慧城市数据中台规范)Collibra技术文档(2024)字段级血缘的挑战与解决路径。自动优化血缘路径,并深化。字段级血缘技术实现方案。Collibra通过。图数据库性能优化原理。

百态·数智思维 | 聚焦大数据、量化与未来AI 1244

芋道框架中上传文件接口文档出错——knife4j4.5.0增强swagger3文档中入参对象中的文件属性字段不显示问题解决

芋道框架-knife4j4.5.0增强swagger3文档中入参对象中的文件属性字段不显示问题解决

猿小白的博客 719

【PLC】三菱plc控件安装 component Movedata had the following error ... Error Number:-119

Windows 10 专业版/企业版本版本号:22H2操作系统内部版本:19045.3448。

少莫千华 8006

SpringBoot中集成Swagger2

Swagger是非常流行的API框架,能够自动生成RESTFul 风格的API文档,还可以在线测试后台接口。使用Swagger你只需要按照它的规范去定义接口及接口相关的信息,再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,以及在线接口调试页面等等。前后端分离的开发模式下,前端通过后端的API文档来进行开发和联调,效率更高。

这是我的笔记本,记录学习历程,分享学习经验,菜鸡一枚,感谢支持! 1444

基于STM32的RS485土壤氮磷钾与PH传感器数据采集与OLED显示实战(附完整代码)

本文详细介绍了基于STM32单片机通过RS485协议采集土壤氮磷钾与PH传感器数据的实战项目。涵盖硬件选型、连接方法、Modbus-RTU通信协议解析、STM32程序实现及OLED显示,提供完整代码和调试技巧,适用于农业物联网环境监测系统。

kotlin6android的博客 341

089、NPU的Chiplet设计:多Die互联与封装

本文深入探讨了NPU Chiplet设计中的多Die互联与封装挑战。作者基于实践经验指出,Chiplet技术虽能突破单芯片算力限制,但面临协议死锁、信号完整性、电源完整性等复杂问题。文章比较了UCIe/BoW等互联协议优劣,分析了硅中介层与EMIB封装方案的取舍,并强调协议轻量化设计的重要性。通过真实案例(如第47层卷积死锁问题)说明credit机制等关键技术细节,给出均衡器优化、调试端口预留等实用建议。最后提出五项核心经验:避免过度依赖标准协议、重视测试点预留、做好电源仿真、优化热管理、建立故障模型,为高

m0_50546716的博客 123

SpringBoot集成Swagger2

SpringBoot集成Swagger Swagger简介 配置Swagger2 swagger扫描指定的包下的接口 配置多个分组 swagger里的controller方法加注释 Swagger实体类加注释

东风麦芽糖 2356

c#仿热血江湖

Int32_1 = (int) table.Rows[i]["FLD_初级附魂"],Int32_2 = (int) table.Rows[i]["FLD_中级附魂"],Int32_3 = (int) table.Rows[i]["FLD_是否绑定"],Int32_0 = (int) table.Rows[i]["FLD_进化"],Form1.smethod_1(2, "加载百宝阁物品----没有百宝阁数据");Form1.smethod_1(2, "加载物品商店----没有物品数据");

weixin_42132177的博客 143

Springfox-swagger2集成SpringBoot2.7.x

Swagger2是一个用于设计、构建和文档化Web API的工具。它允许开发人员定义API的结构、请求和响应格式,并生成交互式的API文档。开发人员在类上使用注解描述接口,Swagger直接在网页上生成和展示API,使得API的开发和维护更加简单和高效。

baomingshu的博客 2003

【2026 Science Robotics】Learning realistic lip motions for humanoid face robots

哥伦比亚大学Yuhang Hu团队提出了一种创新方法,通过10自由度软体嘴唇设计和自监督学习算法解决仿人机器人嘴唇动作僵硬问题。研究采用变分自编码器(VAE)和面部动作Transformer(FAT)模型,将语音信号转化为机器人可执行的电机指令。实验表明,该方法在多语言测试中表现优异,用户偏好率达62.5%,显著提升了口型同步的真实感和流畅度。该成果突破了传统机械结构的限制,为跨越"恐怖谷效应"提供了有效解决方案。

志在山顶的人,不会贪念山腰的风景 311

基于Simulink实现电动汽车动力电池均衡充电策略与管理系统仿真

通过上述步骤,我们成功实现了基于Simulink的电动汽车动力电池均衡充电策略与管理系统仿真。该平台能够全面评估均衡算法的效果,并通过优化设计提高电池组的整体性能和寿命。引入智能算法:结合人工智能技术,实现更智能的均衡策略优化。扩展功能:增加对多种电池类型和工况的支持,提升平台通用性。实验验证:将仿真平台应用于实际硬件,进行实验验证,评估其在实际工况下的表现。

xiaoheshang_123的博客 224

springboot2.x集成swagger保姆级教程

Swagger 是一款用于 API(应用程序接口)设计、开发、文档化及测试的工具框架,可简化 API 全生命周期管理。它通过标准化规范(OpenAPI)定义接口,自动生成交互式文档、客户端 / 服务端代码,支持在线调试,提升前后端协作效率,常见于 RESTful API 开发,核心工具包括 Swagger UI(可视化文档)、Swagger Editor(接口设计)等,让 API 开发更透明、高效。

qq_44959735的博客 1345

Probability and Statistics - 4th edition

Probability and Statistics - 4th edition

Spring Boot 实战:集成Swagger在线调试

在Spring Boot项目中集成Swagger可以让API文档管理和在线调试变得更加便捷。Swagger提供了一个强大的界面,允许开发者设计、构建、文档化和使用RESTful web服务。

qq_33240556的博客 597

文档:亲测可用解决vnc灰屏,黑屏,鼠标大黑叉情况

主要解决vnc-viewer灰屏,黑屏,鼠标大黑叉等现象,详细见文档。

数学建模模型总结

这是本人在两年内准备参加数学建模竞赛搜集到的模型资料,已经经过了本人的筛选和整理,希望能够对准备参加数学建模竞赛的学弟学妹们提供一些帮助!

SpringBoot——SpringBoot集成Swagger生成API文档

SpringBoot——SpringBoot集成Swagger生成API文档

贝尔摩德苦艾酒 8863

复分析 阿尔福斯(Ahlfors) 第三版答案 英文

答案分为十章,有部分习题没有答案,全英文复分析阿尔福斯(Ahlfors) 第三版答案

Java项目中使用Swagger功能

一,Swagger功能是什么呢? 简单说就是生产API接口文档,同时提供在线调试项目API的接口的功能,可以说对推进项目进度非常有利,尤其对前后台分离的情况更加有用; 二,如何在Java项目中使用Swagger功能,欢迎使用推荐的方式 1,过去的Swagger使用方式【不推荐使用】 (1)引入依赖 jar 包,如下: <dependency> <groupId&gt...

shenzhenNBA的专栏 5883

springboot 整swagger knife4j

Swagger knife4j 整合

weixin_59842401的博客 1009

swagger集成到springboot教程

springboot+swagger+mybatis工程,介绍swagger如何集成进springboot工程中,3分钟快速看懂!

程序员小杨哥的博客 3874
上一篇: 微服务 | 我为啥不看好 ServiceMesh
下一篇: Hmily:轻轻松松搞定高并发分布式事务
公众号-芋道源码
博客等级 码龄10年 1639粉丝 377原创
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值