Swagger2

Swagger2 是什么？

Swagger2 是一个用于设计、构建和文档化 API 的工具。它允许开发者在编写代码的同时设计、测试和使用 API。Swagger2 使用 OpenAPI 规范（以前称为 Swagger 规范）来定义 API，并提供了一组工具，包括 Swagger Editor、Swagger UI 和 Swagger Codegen，以简化 API 的设计和文档生成过程。

Swagger2 的主要用途：

API 文档生成：通过注解生成 API 文档，方便开发者和团队理解和使用 API。
API 测试：提供交互式的 Swagger UI，可以直接在 UI 上测试 API。
代码生成：通过 Swagger Codegen 可以生成客户端和服务端的代码，支持多种编程语言。
接口设计：支持 API 设计的过程，帮助规范和标准化接口设计。

Swagger2 相对于传统方式的优势：

自动文档生成：无需手动编写文档，通过注解和规范即可生成详细的 API 文档。
交互式测试：Swagger UI 提供了一个交互式的界面，开发者可以直接在界面上测试 API，省去了使用其他工具的步骤。
标准化接口设计：使用 OpenAPI 规范，可以更规范、统一地进行接口设计，降低沟通成本。
代码生成：可以根据 API 文档生成客户端和服务端的代码，减少手动编写代码的工作量。

Swagger2 的使用：

下面是一个基本的 Spring Boot 项目中集成 Swagger2 的例子：

步骤 1: 添加依赖

在 Maven 项目中，添加 Swagger2 依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version> <!-- 使用最新版本 -->
</dependency>

步骤 2: 创建 Swagger2 配置类

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 指定扫描的包路径
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .description("API documentation for My Spring Boot App")
                .version("1.0")
                .build();
    }
}

在上述配置中，通过 @Bean 注解创建了一个 Docket 实例，用于配置 Swagger2 的行为。api() 方法指定了扫描的包路径，即包含 API 控制器的包。apiInfo() 方法用于设置 API 文档的信息，包括标题、描述和版本号等。

步骤 3: 使用 Swagger UI

启动应用程序后，访问 http://localhost:8080/swagger-ui/index.html 就可以看到 Swagger UI，其中包含了自动生成的 API 文档。

以上只是一个简单的集成示例，实际项目中可以根据需要进行更详细的配置，包括请求头、全局参数等。Swagger2 提供了丰富的注解和配置选项，可以满足不同项目的需求。

MaXiaoTiao

Swagger2

Swagger2