SpringBoot整合Swagger，让开发更遍历

个人简介：Java领域新星创作者；阿里云技术博主、星级博主、专家博主；正在Java学习的路上摸爬滚打，记录学习的过程~
个人主页：.29.的博客
学习社区：进去逛一逛~

---

👇

Swagger介绍

Swagger 是一种流行的开源工具集，用于设计、构建、记录和使用 RESTful Web 服务的 API( https://swagger.io/ )。它包含了一系列工具，可以帮助开发人员在开发 API 时更加高效地进行设计、测试和文档编写。下面是 Swagger 的一些主要功能和组件：

1. API 文档自动生成： Swagger 可以根据代码中的注解自动生成 API 文档。开发人员只需要在代码中添加一些特定的注解，描述 API 的路径、参数、响应等信息，Swagger 就可以自动扫描代码并生成相应的 API 文档。
2. 可视化 API 文档： Swagger 生成的 API 文档以可视化的形式呈现，包括 API 的路径、HTTP 方法、参数、响应等信息，使开发人员可以清晰地了解 API 的使用方式和接口规范。
3. 交互式 API 测试工具： Swagger UI 是 Swagger 提供的一个交互式 API 测试工具，可以让开发人员直接在浏览器中测试 API，无需使用额外的工具或插件。通过 Swagger UI，开发人员可以输入参数、发送请求，并查看实际的响应结果，从而快速验证 API 的正确性和可用性。
4. API 文档的版本控制： Swagger 支持多版本的 API 文档管理，开发人员可以为不同版本的 API 编写不同的文档，并通过 Swagger UI 来方便地切换和查看不同版本的 API。
5. 集成开发环境支持： Swagger 可以集成到各种常见的集成开发环境（IDE）中，如 Eclipse、IntelliJ IDEA 等，提供了便捷的 API 设计和文档编写功能。
6. 与多种编程语言和框架的兼容性： Swagger 不仅支持 Java，还支持多种其他编程语言和框架，如 Python、Node.js、Ruby 等，开发人员可以在不同的项目中使用 Swagger 来进行 API 的设计和文档编写。

综合来说，Swagger 提供了一套完整的工具集，帮助开发人员更加高效地设计、构建和文档化 RESTful API，提升了团队协作效率，降低了开发成本，同时也提升了 API 的可读性和可维护性。

---

SpringBoot整合swagger

1 引入Maven坐标：

Spring已经将Swagger纳入自身的标准，建立了Spring-swagger项目，现在叫Springfox。通过在项目中引入Springfox ，即可非常简单快捷的使用Swagger。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
</dependency>

2 创建一个Swagger配置类 ：

SwaggerConfiguration.java

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author .29.
 * @create 2024-05-13 10:43
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInfo())
                .select()
                // 要扫描的API(Controller)基础包
                .apis(RequestHandlerSelectors.basePackage("com.heima"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo buildApiInfo() {
        Contact contact = new Contact(".29.","","");
        return new ApiInfoBuilder()
                .title(".29.仿今日头条-平台管理API文档")
                .description(".29.仿今日头条后台api")
                .contact(contact)
                .version("1.0.0").build();
    }
}

让我解释一下这段代码的主要内容：

1. @Configuration：这个注解表明这是一个配置类，它会在 Spring 应用程序启动时被加载。
2. @EnableSwagger2：这个注解用于启用 Swagger2 的支持。
3. @Bean：这个注解表明 buildDocket() 方法将会产生一个 Spring Bean，并将其加入到 Spring 容器中。
4. buildDocket() 方法：这个方法创建并配置了一个 Docket 对象，用于配置 Swagger 的基本信息和扫描规则。具体来说：
   • 使用 DocumentationType.SWAGGER_2 指定了 Swagger 的文档类型为 Swagger 2.0。
   • 使用 apiInfo(buildApiInfo()) 方法设置 API 文档的基本信息，包括标题、描述、联系人信息和版本号。
   • 使用 select() 方法开始配置 API 选择器，通过 apis(RequestHandlerSelectors.basePackage("com.heima")) 指定了要扫描的 API(Controller) 的基础包路径为 “com.heima”。
   • 使用 paths(PathSelectors.any()) 方法指定了所有路径都应该被包含在 API 文档中。
   • 最后使用 build() 方法来构建 Docket 对象。
5. buildApiInfo() 方法：这个方法创建并配置了 ApiInfo 对象，用于设置 API 文档的基本信息。具体来说：
   • 创建了一个 Contact 对象，用于设置联系人信息。
   • 使用 ApiInfoBuilder 构建器设置了 API 文档的标题、描述、联系人信息和版本号。
   • 最后使用 build() 方法构建 ApiInfo 对象。

这段代码配置了 Swagger 生成 API 文档的基本信息，并指定了扫描哪些包中的 Controller 类来生成 API 文档。

3 设置Swagger相关功能的自动配置：

resources目录下新增文件：resources/META-INF/Spring.factories

# Spring自动配置相关参数（参数通常是一个以逗号分隔的类名列表，每个类名表示一个自动配置类。）
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  com.heima.common.swagger.SwaggerConfiguration

⭐在Java类中添加Swagger的注解即可生成Swagger接口文档⭐

⭐访问Swagger文档：http://{你的IP}:{你的项目服务端口}/swagger-ui.html⭐

http://localhost:51801/swagger-ui.html

Swagger常用注解介绍

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数的描述信息

@ApiModel：用对象来接收参数

@ApiModelProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：一个请求参数

@ApiImplicitParams：多个请求参数的描述信息

@ApiImplicitParam属性：

属性	取值	作用
paramType		查询参数类型
	path	以地址的形式提交数据
	query	直接跟参数完成自动映射赋值
	body	以流的形式提交 仅支持POST
	header	参数在request headers 里边提交
	form	以form表单的形式提交 仅支持POST
dataType		参数的数据类型 只作为标志说明，并没有实际验证
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

---