《Spring Boot 集成 Swagger：打造高效接口文档与开发体验》

news/2024/9/20 4:00:28/ 标签: spring boot, 后端, java, Swagger

Swagger_0">Swagger

一.导语：

​ 相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

Swagger_6">二.Swagger是什么？它能干什么？

https://swagger.io/

image-20240826113757700

​ 发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

框架说明

​ 现在SWAGGER官网主要提供了几种开源工具，提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果。

  • Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

  • **Swagger UI:**提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

  • Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

  • Swagger Inspector: 和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

  • Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

    PS：

  • Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。其实swagger是有两个版本的，区别还挺大的，一个是swagger-ui也就是swagger1，还有一个是springfox-swagger也就是swagger2;

总结：

​ Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。使用Swagger，就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

​ Springfox-swagger,则可以通过扫描代码去生成这个描述文件，连描述文件都不需要再去维护了。所有的信息，都在代码里面了。代码即接口文档，接口文档即代码。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：

​ 1.接口的文档在线自动生成

​ 2.功能测试

Swagger_44">**三.**SpringBoot集成Swagger

3.1 初始实现步骤
1.添加Maven依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency><dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

java">2.编写一个配置类-SwaggerConfig来配置 Swagger@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {
}3.访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；
注意:
如果启动报错空指针是因为springboot2.6.0中将SpringMVC 默认路径匹配策略从AntPathMatcher 
更改为PathPatternParser，导致出错可以在启动类上加上@EnableWebMvc注解或者在配置中切换为
原先的AntPathMatcherspring.mvc.pathmatch.matching-strategy=ant_path_matcher.
Swagger_78">3.2 配置Swagger
java">1.Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger
@Bean //配置docket以配置Swagger具体参数
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2);}2.可以通过apiInfo()属性配置文档信息
//配置文档信息
private ApiInfo apiInfo() {
Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
return new ApiInfo("Swagger学习", 
// 标题"学习演示如何配置Swagger", // 描述
"v1.0", // 版本
"http://apesource.com", // 组织链接
contact, // 联系人信息
"Apach 2.0 许可", // 许可
"许可链接", // 许可连接
new ArrayList<>()// 扩展
);
}3.Docket 实例关联上 apiInfo()
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}4.重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果；
3.3 配置扫描接口
java">1.构建Docket时通过select()方法配置怎么扫描接口
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫
描接口
.apis(RequestHandlerSelectors.basePackage("com.apesource.swagger.controller"))
.build();
}2.重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类
3.除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式
any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解
的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口4.除此之外，我们还可以配置接口扫描过滤
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫
描接口
.apis(RequestHandlerSelectors.basePackage("com.apesource.swagger.controller"))
// 配置如何通过path过滤,即这里只扫描请求以/apesource开头的接口
.paths(PathSelectors.ant("/apesource/**"))
.build();
}5.这里的可选值还有
any() // 任何请求都扫描
none() // 任何请求都不扫描
regex(final String pathRegex) // 通过正则表达式控制
ant(final String antPattern) // 通过ant()控制
3.4 配置API分组
java">1.如果没有配置分组，默认是default。通过groupName()方法即可配置分组
@Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.groupName("hello") // 配置分组
// 省略配置....
}2.重启项目查看分组
3.如何配置多个分组？配置多个分组只需要配置多个docket即可
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
3.5 拓展：其他皮肤
我们可以导入不同的包实现不同的皮肤定义
1.默认的访问 http://localhost:8080/swagger-ui.html
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>2.bootstrap-ui 访问 http://localhost:8080/doc.html
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.1</version>
</dependency>

四.常用注解

swagger通过注解生成接口文档，包括接口名、请求方法、参数、返回信息的等等。
@Api：修饰整个类，描述Controller的作用
语法：@Api(tags="说明该类的作用，可以在UI界面上看到的注解"，value = "/类的访问路径",
description = "类的文字描述")@ApiOperation：描述一个类的一个方法，说明方法的作用
语法：@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回
参数类型”, notes = “接口发布说明”）@ApiImplicitParam：一个请求参数
语法：@ApiImplicitParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描
述”,dateType="变量类型”,paramType="请求方式”
· header --> 请求参数的获取：@RequestHeader· query --> 请求参数的获取：@RequestParam· path（用于restful接口）--> 请求参数的获取：
@PathVariable· body（不常用）· form（不常用）
）@ApiImplicitParams： 多个请求参数
@ApiParam：单个参数描述
语法：@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描
述”,dateType="变量类型”,paramType="请求方式”）@ApiResponse：HTTP响应其中1个描述,响应配置
语法：@ApiResponse(code = 400, message = "Invalid user supplied")@ApiResponses：HTTP响应整体描述
语法：@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })@ApiModel：用对象实体来作为入参
@ApiProperty：用对象接实体收参数时，描述对象的一个字段
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息

案例代码

java">/**** Swagger2配置类* 通过@Configuration注解，让Spring来加载该类配置。* 再通过@EnableSwagger2注解来启用Swagger2。* */
@EnableSwagger2
@Configuration
public class SwaggerConfig {/*** 创建API应用* apiInfo() 增加API相关信息* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，* 本例采用指定扫描的包路径来定义指定要建立API的目录。**/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.ywq.springbootbysjday1.controller"))//扫描路径.paths(PathSelectors.any())//定义哪些路径的接口需要生成文档.build();}/*** 创建该API的基本信息（这些基本信息会展现在文档页面中）* 访问地址：http://项目实际地址/swagger-ui.html*/private ApiInfo apiInfo() {Contact  contact = new Contact("ywq", "http://www.apesource.com", "wangyanyi_enginner@163.com");return new ApiInfoBuilder().title("疫情防控数据采集发布平台")//文档首页标题.version("1.0")//文档版本.description("新型冠状病毒肺炎 - 疫情防控数据采集发布平台后端接口说明文档")//文档描述信息.contact(contact)//创建者信息.build();}@RestController
@RequestMapping("/user")
@Api(tags = "一个用来测试swagger注解的控制器",value = "/user")
public class UserController {/************************************修饰参数****************************************/@GetMapping(value ="/findByName")@ApiOperation(value = "通过名字查询的方法")public Result findByName(@RequestParam String userName){if(userName.equals("赵老师")){return new Result(true,"查询成功","赵老师");}else{return new Result(false,"查询失败",null);}}
//
//    @GetMapping(value ="/findByNameAndSex")
//    @ApiOperation(value="根据用户名与性别查询")
//    public Result findByNameAndSex(String userName,String sex){
//        if(userName.equals("赵老师")){
//            return new Result(true,"查询成功","赵老师");
//        }else{
//            return new Result(false,"查询失败",null);
//        }
//    }
//
//
//
//    @GetMapping(value ="/findByAge/{age}")
//    @ApiOperation(value="根据用年龄查询", notes="描述的具体信息可以省略")
//    public Result findByAge(@PathVariable("age") Integer userAge){
//        if(userAge > 18){
//            return new Result(true,"查询成功","赵老师");
//        }else{
//            return new Result(false,"查询失败",null);
//        }
//    }
//
//    @PostMapping(value ="/saveAdmin1")
//    @ApiOperation(value="新增管理员信息1", notes="描述的具体信息可以省略")
//    public Result saveAdmin1(Admin admin){
//        if(admin.getAdminId() > 10){
//            return new Result(true,"查询成功","赵老师");
//        }else{
//            return new Result(false,"查询失败",null);
//        }
//    }
//@PostMapping(value ="/saveAdmin2")@ApiOperation(value="新增管理员信息2", notes="描述的具体信息可以省略")public Result saveAdmin2(@RequestBody Admin admin){if(admin.getAdminId() > 10){return new Result(true,"查询成功","赵老师");}else{return new Result(false,"查询失败",null);}}//
//    /************************************返回值****************************************/
//    @DeleteMapping(value ="/deleteById/{id}")
//    @ApiOperation(value="根据用户编号删除信息", notes="")
//    public Admin deleteById(@PathVariable("id") Integer userId){
//        return new  Admin(1,"张三","张三","张三",new Date(System.currentTimeMillis()));
//    }@ApiModel(value = "管理员实体列")
public class Admin {@ApiModelProperty(name = "adminId",value = "管理员编号",example = "001")private int adminId;//管理员编号@ApiModelProperty(name = "adminLoginAccount",value = "管理员登录账号",example = "13991267980")private String adminLoginAccount;//管理员登录账号（手机号码）@ApiModelProperty(name = "adminLoginPassword",value = "登录登录密码",example = "123456")private String adminLoginPassword;//登录登录密码（默认为手机号码后8位）@ApiModelProperty(name = "adminRole",value = "管理员角色",example = "管理员")private String adminRole;//管理员角色（超级管理员或普通管理员）@ApiModelProperty(name = "adminLastLoginTime",value = "最后登录时间")private Date adminLastLoginTime;//最后登录时间（2020年03月14日 15:30:40）
}@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "控制器方法返回值",description = "自定义结果集")
public class Result {@ApiModelProperty(name = "falge",value = "结果集状态",example = "true")private boolean falge;//状态@ApiModelProperty(name = "message",value = "提示信息",example = "查询成功")private String message;//提示信息@ApiModelProperty(name = "data",value = "返回数据")private Object data;//返回数据
}

http://www.ppmy.cn/news/1516658.html

相关文章

Vue(1)——创建实例

Vue(1)——创建实例

Vue创建实例 Vue是用于构建用户界面的渐进式框架。 创建Vue实例&#xff0c;初始化渲染 准备容器引包(开发版本/生产版本)创建Vue实例指定配置项&#xff0c;渲染数据 el指定挂载点 data提供数据 <!-- 准备容器 --><div id"app"><h1>{{msg}}<…
阅读更多...
【C#】【EXCEL】Bumblebee/Classes/ExFont.cs

【C#】【EXCEL】Bumblebee/Classes/ExFont.cs

Bumblebee/Classes/ExFont.cs Flow diagram 根据您提供的代码和要求&#xff0c;我将创建一个流程图来展示ExFont类的结构。这个流程图将使用中英双语标注&#xff0c;并对应到代码中的英文。 #mermaid-svg-uaTfYlccE1dTu1A6 {font-family:"trebuchet ms",verdana,…
阅读更多...
git-20240822

git-20240822

目录 初始化仓库 Git init Git init project --bare 查看提交的记录 git log --prettyoneline 查看当前git远程库地址 git remote -v 查看详细提交记录 git log 撤出暂存区的文件 git reset HEAD file(.代表全部文件&#xff09; 提交数据到远程仓库 git config --global push.…
阅读更多...
高级前端工程师React面试题

高级前端工程师React面试题

什么是React&#xff1f;React和Vue有什么区别&#xff1f;请描述React的组件生命周期。什么是JSX&#xff1f;React中的state和props有什么区别&#xff1f;请解释React中的虚拟DOM。什么是React Hooks&#xff1f;useState和useEffect Hooks有什么用途&#xff1f;在React中&…
阅读更多...
docker常见指令——镜像指令and容器指令

docker常见指令——镜像指令and容器指令

docker镜像指令 查看镜像 docker images 搜索镜像 docker search 镜像名 上传镜像 docker pull 镜像名 或 docker pull 镜像名&#xff1a;tag 注:不加:tag表示最新版本 &#xff0c;加:tag表示指定版本 运行镜像 docker run 镜像名 保存镜像 docker save 镜像名/镜像id -o 要…
阅读更多...
【前端基础篇】JavaScript基础介绍

【前端基础篇】JavaScript基础介绍

文章目录 前言初始JavaScriptJavaScript是什么发展历史JavaScript和HTML和CSS之间的关系JavaScript的运行过程JavaScript的组成 JavaScript的书写形式行内式内嵌式外部式注释 输入输出基础语法变量数据类型 运算符 JavaScript对象对象new关键字 常用对象数组创建数组数组操作函…
阅读更多...
若依权限控制前端+后端实现思路梳理（PreAuthorize、hasPermi、v-hasPermi）

若依权限控制前端+后端实现思路梳理（PreAuthorize、hasPermi、v-hasPermi）

一、权限控制引发的思考 引言 最近接手了公司的一个项目&#xff0c;实施反馈说&#xff0c;客户那边要求对不同的权限的用户操作权限做限制。场景就是&#xff0c;比如一个项目列表&#xff0c;这部分数据有可能是针对某个公司某个部门的&#xff0c;对应不同的部门用户能看…
阅读更多...
Leetcode Hot 100刷题记录 -Day2（哈希表）

Leetcode Hot 100刷题记录 -Day2（哈希表）

一、字母异位词分组 问题描述&#xff1a; 给你一个字符串数组&#xff0c;请你将 字母异位词 组合在一起。可以按任意顺序返回结果列表。字母异位词 是由重新排列源单词的所有字母得到的一个新单词。 简单理解&#xff1a;字母异位词就是字母个数和种类都相同&#xff0c;但字…
阅读更多...
高性能web服务器4——Nginx反向代理A

高性能web服务器4——Nginx反向代理A

Nginx 反向代理 Nginx 的反向代理功能是其最强大的特性之一&#xff0c;它允许 Nginx 作为中间层来接收客户端的请求&#xff0c;并将这些请求转发到后端服务器。这种架构不仅可以提高安全性&#xff0c;还可以实现负载均衡、缓存和内容过滤等功能。本文将详细介绍 Nginx 反向…
阅读更多...
深度学习-11-为什么AI需要GPU

深度学习-11-为什么AI需要GPU

几十年前，CPU 作为通用处理器几乎处理所有计算任务，那个时代的显卡有助于加快应用程序中图形的绘制速度。但在今天ChatGPT引爆的人工智能iPhone时刻，GPU成为了整个行业最具主导地位的芯片之一。大家都在抢购GPU，龙头企业英伟达也因此赚的盆满钵满。 服务器中有处理器、内存…
阅读更多...
【C++ 面试 - 内存管理】每日 3 题（三）

【C++ 面试 - 内存管理】每日 3 题（三）

✍个人博客&#xff1a;Pandaconda-CSDN博客 &#x1f4e3;专栏地址&#xff1a;http://t.csdnimg.cn/fYaBd &#x1f4da;专栏简介&#xff1a;在这个专栏中&#xff0c;我将会分享 C 面试中常见的面试题给大家~ ❤️如果有收获的话&#xff0c;欢迎点赞&#x1f44d;收藏&…
阅读更多...
如何解决 Cloudflare | 使用 Puppeteer 和 Node.JS

如何解决 Cloudflare | 使用 Puppeteer 和 Node.JS

我认为&#xff0c;现在自动化任务越多&#xff0c;越能体现它们的价值&#xff0c;因此挑战也变得更加明显和困难。例如&#xff0c;Cloudflare 目前提供了强有力的安全措施来保护网站免受所有形式的自动化工具的侵扰。 但对于从事自动化项目&#xff08;如网络爬虫、数据提取…
阅读更多...
依赖包更新了但是没有release,如何安装更新的依赖包

依赖包更新了但是没有release,如何安装更新的依赖包

问题描述:有一个python仓库mmrotate,仓库更新了support training mmrotate on NPU (#806)这个commit, 但是pip没有release,怎么安装这个新的commit? 解决: 要安装未发布的commit&#xff0c;可以通过从Python仓库直接安装特定commit的版本。以下是安装mmrotate仓库中支持在NP…
阅读更多...
PG库表被锁怎么办？

PG库表被锁怎么办？

查询PG库是否有被锁的表 SELECT t.relname AS table_name,l.locktype,l.database,l.pid,l.mode,l.granted FROM pg_locks l JOIN pg_class t ON l.relation t.oid WHEREt.relkind r ANDl.mode IS NOT NULL;解锁表 根据查询结果中的进程ID&#xff08;‌PID&#xff09;‌&a…
阅读更多...
CentOS网址

CentOS网址

CentOS网址 CentOS镜像
阅读更多...
网络通信编程UDP/TCP

网络通信编程UDP/TCP

一、不同体系结构间的互联互通 通信本质&#xff1a;不同主机上进程间的通信。通过 IP 标识网络中的一台主机&#xff0c;本质上是 32 位的整型数据&#xff1b;通过端口号标识某个进程&#xff0c;本质上是 16 位的整型数据。网络模型&#xff1a;主要有 C/S&#xff08;客户…
阅读更多...
文件上传漏洞（看过就能学会）

文件上传漏洞（看过就能学会）

一、什么是文件上传漏洞&#xff1f; 在有上传功能的系统中&#xff0c;如果应用程序没有对用户上传的文件做严格的校验&#xff0c;那么可能会导致用户上传脚本文件&#xff0c;然后用户再通过访问这些文件的方式&#xff0c;来达到执行该脚本文件&#xff0c;从而控制服务器…
阅读更多...
一文讲明白如何将shell脚本闭源

一文讲明白如何将shell脚本闭源

目录 目的使用帮助举例实现：打包查看检查打包后的文件验证问题1：注意事项：目的 我们使用的脚本都是可以直接查看，因为这个是一个解释性的执行过程，那么有没有可能让脚本闭源呢,也就是说，我们辛苦的写的脚本，不想让别人看到，有没有好的办法呢？ 这里我们可以使用makese…
阅读更多...
Kakfa的核心概念-Replica副本（kafka创建topic并指定分区和副本的两种方式）

Kakfa的核心概念-Replica副本（kafka创建topic并指定分区和副本的两种方式）

Kakfa的核心概念-Replica副本&#xff08;kafka创建topic并指定分区和副本的两种方式&#xff09; 1、kafka命令行脚本创建topic并指定分区和副本2、springboot集成kafka创建topic并指定分区和副本2.1、springboot集成kafka2.1.1、springboot集成kafka创建topic并指定5个分区和…
阅读更多...
使用 jar-analyzer 和dbeaver 分析java

使用 jar-analyzer 和dbeaver 分析java

https://github.com/jar-analyzer/jar-analyzer 可以进行jar分析&#xff0c;包括method调用 分析完可以通过界面进行一些分析&#xff0c;如果复杂还可以用DbWeaver 打开数据库进行分析
阅读更多...
最新文章

Copyright @ 2022~2023

友情链接： 我的编程经验分享 一条长河网 尧图网站开发 尧图建网站