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

news2024/12/23 10:17:29

Swagger

一.导语:

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

二.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.功能测试

**三.**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>
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.
3.2 配置Swagger
1.Swagger实例BeanDocket,所以通过配置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 配置扫描接口
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分组
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 :发生错误返回的信息

案例代码

/**
 *
 * Swagger2配置类
 * 通过@Configuration注解,让Spring来加载该类配置。
 * 再通过@EnableSwagger2注解来启用Swagger2。
 * */
@EnableSwagger2
@Configuration
public class SwaggerConfig {

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     */
    @Bean
    public 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.coloradmin.cn/o/2077201.html

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈,一经查实,立即删除!

相关文章

MindSearch 部署

任务 按照教程&#xff0c;将 MindSearch 部署到 HuggingFace 并美化 Gradio 的界面&#xff0c;并提供截图和 Hugging Face 的Space的链接。 创建开发机 & 环境配置 mkdir -p /root/mindsearch cd /root/mindsearch git clone https://github.com/InternLM/MindSearch.…

dbsyncer同步mysql数据

1 概述 DBSyncer&#xff08;代码地址&#xff1a;https://github.com/86dbs/dbsyncer&#xff09;是一款开源的数据同步中间件&#xff0c;提供MySQL、Oracle、SqlServer、PostgreSQL、Elasticsearch(ES)、Kafka、File、SQL等同步场景。支持上传插件自定义同步转换业务&#…

人脸质量评价:深入解析和实现

人脸质量评价&#xff1a;深入解析和实现 引言 随着人工智能和计算机视觉技术的飞速发展&#xff0c;人脸识别已成为许多领域的关键技术之一。然而&#xff0c;人脸识别的准确性高度依赖于输入的人脸图像质量。因此&#xff0c;人脸质量评价作为人脸识别前的预处理步骤&#…

如何利用电商 API 数据分析助力精准选品!

电商 API 数据分析在选品过程中起着至关重要的作用&#xff0c;它们之间有着密切的关系&#xff1a; 一、提供市场趋势洞察 热门商品识别&#xff1a; 通过分析电商 API 中的销售数据&#xff0c;包括商品的销售量、销售额、销售频率等指标&#xff0c;可以快速准确地识别出当…

清华计算几何-线段求交与BO算法

单轴线段求交 给定单边轴下, N定线段&#xff0c;检查出相交的线段. 解法一: 暴力求解 遍历所有线段对&#xff0c;进行相交判断, 算法复杂度为O(n2) 解法二: LR扫描 把每条线段的头尾认定为L和R。对所有点进行排序&#xff0c;如果每两个点满足LL或者RR&#xff0c;则对应…

Leetcode JAVA刷刷站(97)交错字符串

一、题目概述 二、思路方向 为了验证字符串 s3 是否由 s1 和 s2 交错组成&#xff0c;我们可以使用动态规划&#xff08;Dynamic Programming, DP&#xff09;的方法来解决这个问题。 首先&#xff0c;我们需要定义状态 dp[i][j]&#xff0c;它表示 s1 的前 i 个字符和 s2 的前…

DocuSign集成方案 | 结合 DocuSign 与 Oracle,加快业务完成速度!

DocuSign for Oracle 集成将 DocuSign 的电子签名功能与 Oracle 的项目生命周期管理 (PLM) 解决方案相结合 DocuSign 和 Oracle 是两家全球领先的技术公司&#xff0c;它们都致力于帮助企业简化和自动化流程。DocuSign 是电子签名领域的领导者&#xff0c;其解决方案可帮助企业…

【操作系统】实验:进度调度(2)

目录 一、实验目的 二、实验要求 三、实验步骤 四、核心代码 五、记录与处理 六、思考 七、完整报告和成果文件提取链接 一、实验目的 1、掌握高优先权调度算法 2、理解时间片、优先权、抢占等基本概念。 二、实验要求 1. 优先权属于静态优先权&#xff1b; 2. 进入 …

DevOps实现CI/CD实战(五)- Jenkins流水线Pipeline-更新中..

九、 Jenkins流水线pipeline Jenkins流水线任务介绍 之前采用Jenkins的自由风格构建的项目&#xff0c;每个步骤流程都要通过不同的方式设置&#xff0c;并且构建过程中整体流程是不可见的&#xff0c;无法确认每个流程花费的间&#xff0c;并且问题不方便定位问题。Jenkins的…

工程数学与数学建模在编程与算法设计中的应用(下)

目录 引言 第三部分&#xff1a;工程数学在算法设计与优化中的应用 3.1 微分方程与动力系统模拟 常微分方程&#xff08;ODE&#xff09;在动态系统中的应用 偏微分方程&#xff08;PDE&#xff09;在图像处理与物理模拟中的应用 总结 3.2 概率论与数理统计在机器学习中的…

若依将登录用户的userId自动加载到查询中

点击搜索&#xff0c;会将登录用户的userId作为搜索条件&#xff0c;去查询。 新版本自动存储了userId&#xff0c;我们不用改&#xff0c;只要知道如何引用。 前端使用 在对应的vue文件&#xff0c;查询queryParams 加查询的值 然后参考他的 添加store import store from &…

i.MX6裸机开发(11)——DDR测试

本章参考资料&#xff1a;《IMX6ULRM》(参考手册)。 学习本章时&#xff0c;配合《IMX6ULRM》Chapter 33: Multi Mode DDR Controller (MMDC) 一起阅读&#xff0c;效果会更佳&#xff0c;特别是涉及到寄存器说明的部分。 特别说明&#xff0c;本书内容是以i.MX6U系列控制器资…

Serdes系统中的CTLE技术

典型的SerDes系统包含输入数据、串行器、发射机&#xff08;TX&#xff09;、信道、接收机&#xff08;RX&#xff09;、解串器和输出数据。串行数据比特流被输入到发送器。发射机由均衡器&#xff08;EQ&#xff09;和包括封装效果的线性模拟后端组成。传输后端和接收器前端之…

JAVA语言开发环境配置详细讲解

​ ​ 您好&#xff0c;我是程序员小羊&#xff01; 前言 Java是一门广泛应用于软件开发领域的编程语言&#xff0c;自1995年由Sun Microsystems首次发布以来&#xff0c;经过多年的发展&#xff0c;已经成为业界的重要编程语言之一。Java以其“编写一次&#xff0c;到处运行”…

【计算机网络】电路交换、报文交换、分组交换

电路交换&#xff08;Circuit Switching&#xff09;&#xff1a;通过物理线路的连接&#xff0c;动态地分配传输线路资源 ​​​​

IDEA/Pycharm/Goland/jetbrains2024.2全家桶汉化失败问题解决

近期,jetbrains全家桶更新到了2024.2版本,不少人反馈到,下载安装之后,按照以前的汉化方式进行汉化的之后,并没有生效。本章教程,提供此问题的解决方案,亲测有效。 JetBrains 是一家总部位于捷克布拉格的软件开发公司,成立于 2000年。该公司以开发高效、智能的开发工具和…

基于SparkGraphX实现标签传播(LPA)算法

基于SparkGraphX实现标签传播&#xff08;LPA&#xff09;算法 标签传播算法&#xff08;LPA&#xff09;与Louvain一样&#xff0c;同样是一种常用的社群发现算法&#xff0c;它的基本思想是让图中的节点根据邻居节点的标签&#xff08;即社区信息&#xff09;来更新自己的标…

第J1周:ResNet-50算法实战与解析(TensorFlow版)

>- **&#x1f368; 本文为[&#x1f517;365天深度学习训练营]中的学习记录博客** >- **&#x1f356; 原作者&#xff1a;[K同学啊]** 本周任务&#xff1a; 1.请根据本文TensorFlow代码&#xff0c;编写出相应的pytorch代码 2.了解残差结构 3.是否可以将残差模块融…

Mybatis的搭建以及使用

一&#xff0c;如何搭建Mybatis 1&#xff0c;创建一张表和表对应的实体类 2.导入 MyBatis jar 包,mysql 数据库驱动包 <dependency> <groupId>org.mybatis</groupId> <artifactId>mybatis</artifactId> <version>3.4.2</version> …

ICML 2024 顶级论文:机器学习有什么新进展?

在本周的文章中&#xff0c;我打算探讨在国际机器学习大会 ICML 上发表的论文&#xff0c;该大会目前于 2024 年 7 月 21 日至 27 日在奥地利首都维也纳举行。与其他顶级人工智能会议一样&#xff0c;每年都会有数千篇论文提交&#xff0c;但录取率相对较低&#xff08;过去三年…