SpringBoot-SpringBoot整合Swagger使用教程(图文介绍，一篇就够了)

前言

日常开发中，接口都是和开发文档相结合的。不论是和前端对接还是三方对接亦或者是接口留档，当我们开发完接口后，都需要去创建对应的接口文档。而修改接口后也要修改相对应的接口文档，但是这个真的很容易疏漏。而且相对于繁重的开发任务而言，维护文档又是一个同样让人心累的事情。
那么有没有能针对我们的接口自动生成接口说明的工具呢，这样我们就不需要特意去生成和实时的去维护api文档？答案当然是-有，这就是今天要介绍的Swagger。

Swagger介绍

Swagger最初是由Tony Tam创建的一个开源项目，旨在提供一种描述RESTful API的标准化语言。随着时间的发展，Swagger逐渐演变成OpenAPI Specification（OAS），这是一个独立于任何特定实现的开放标准，用于描述RESTful Web服务。Swagger UI和Swagger Editor则是基于该规范的两个重要工具，它们分别用于可视化和编辑API文档。通过它们我们就可以实现自动生成和更新文档。

优点

1、标准化的API描述：
Swagger遵循OpenAPI规范，提供了一种标准化的方式来描述API，包括路径、方法、参数、响应等，这使得API文档易于理解且具有一致性。
2、交互式文档：
Swagger UI能够根据OpenAPI规范自动生成一个动态的、可交互的文档界面。开发者和用户可以直接在这个界面上尝试调用API，查看请求和响应示例，极大地提升了API的可用性和可测试性。
3、自动化生成客户端代码：
Swagger Codegen工具可以根据API的定义自动生成多种编程语言的客户端代码和服务器端接口代码，大大节省了开发时间。
4、简化文档维护：
因为API的描述与实际实现紧密相连，当API发生变化时，文档可以自动更新，避免了手动维护文档带来的不一致性和遗漏。
5、促进团队协作：
Swagger提供了一个共同的语言，使得开发人员、产品经理、测试人员和文档编写者能够基于同一套文档进行沟通，提高了团队的协同效率。
6、支持多语言和框架：
Swagger兼容多种后端技术和语言，如Java、Python、Node.js等，几乎可以无缝融入任何现有的技术栈。
7、便于API治理：
Swagger的标准化描述使得API的版本控制、权限管理、流量监控等治理工作变得更加容易和高效。

下面我们就来看一下如何在我们的项目中集成Swagger

添加pom依赖

说明：下面截图给出的非官方版本的UI依赖，至于为什么，博主稍后会给出解释。

在这里插入图片描述

        <!-- swagger的UI可视化界面 git版本--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.8.1</version></dependency><!-- swagger的UI可视化界面 官方版本，注意版本号一致--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.8.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency>

上面给出了两个不同版本的Swagger UI可视化界面依赖。首先最上面的是博主使用的git版本，下面给出的是官方版本UI界面，二者选择其一即可。二者界面区别下面单独给出。
注意：若选择官方UI界面，需要注意版本号问题，要与下面的springfox-swagger2使用同一个版本号，否则会启动异常。

设置Swagger配置类

@Configuration
@EnableSwagger2
@Profile({"dev", "test", "local"}) // 设置swagger的使用环境(防止prod环境api泄露)
public class Swagger2Config {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// 对某些api进行监控
//或 .apis(RequestHandlerSelectors.basePackage(“com.springboot.demo”)).apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).paths(PathSelectors.any()) // 对所有路径进行监控.build();}// 设置swagger的api相关信息private ApiInfo apiInfo() {return new ApiInfoBuilder().title("local-project-api").description("本地接口api").version("1.0").build();}}