Swagger升级指南：Swagger2与Swagger3注解差异揭秘

在API开发的世界里，Swagger已经成为了一个不可或缺的工具，它让API的文档化和前后端的协作变得前所未有地简单。随着Swagger的进化，我们迎来了Swagger3，也被称为OpenAPI Specification 3.0。本篇博客将带大家深入了解Swagger2和Swagger3（OpenAPI 3）之间的主要区别，特别是在注解上的变化，并且提供一些实用的Java示例，帮助大家平滑过渡到Swagger的新时代。

引言

随着RESTful API的普及，API文档成为了开发过程中的一个重要组成部分。Swagger作为API文档的领先工具，提供了一种标准化的方法来设计、构建、文档化以及使用REST API。Swagger2长期以来一直是开发者的首选，但随着Swagger3的出现，很多开发者面临着升级的选择。本文旨在帮助你理解两个版本之间的差异，并通过示例指导如何迁移。

Swagger简介

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。总体来说，Swagger提供了一套标准的注解，开发者可以通过这些注解来描述他们的API，然后Swagger可以根据这些注解生成可交互的API文档。

Swagger2与Swagger3的核心区别

Swagger3是在Swagger2的基础上进行了改进和扩展，它实现了OpenAPI Specification 3.0，这个最新版本的规范带来了许多新特性和改进，如对回调、链式操作、组件重用等支持。

注解对比

通用注解变化

在Swagger3中，一些基本注解发生了变化。例如，@Api注解在Swagger3中被弃用，因为Swagger3鼓励使用更自然的方式来组织API文档。

API信息配置

在Swagger2中，你可能习惯了使用@Api注解和Docket配置API的基本信息。而在Swagger3中，这些信息通常在OpenAPI配置类中通过构建OpenAPI实例来设置。

路径和操作注解

Swagger2的@ApiOperation、@ApiImplicitParam和@ApiImplicitParams注解在Swagger3中被@Operation和@Parameter注解替代，提供了更多的配置选项和更好的可读性。

参数注解

Swagger3引入了@Parameter注解来描述参数，它提供了更多的属性来定义参数的元数据，如schema、example、content等。

模型注解

Swagger3通过使用@Schema注解来描述数据模型，这是一个强大的注解，它提供了对模型定义的完全控制。

实践：从Swagger2迁移到Swagger3

迁移过程中，你需要注意替换过时的注解，并且调整配置类以适应新的OpenAPI 3.0结构。这通常涉及到替换Docket配置以及重构现有的注解。

代码示例

让我们看一下在Swagger2和Swagger3中如何配置API信息和使用注解。

Swagger2配置示例

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("My API")
                        .description("API Description")
                        .version("1.0")
                        .build());
    }
}

Swagger3配置示例

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("spring")
                .packagesToScan("com.example")
                .build();
    }

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("My API")
                        .description("API Description")
                        .version("v2.0"));
    }
}

在上面的Swagger3配置中，我们使用了GroupedOpenApi来创建API组，并且使用了OpenAPI类来构建API的元信息。

Swagger2与Swagger3注解的主要区别

Swagger3基于OpenAPI Specification 3.0，这个新版本的规范带来了更多的灵活性和表达力。以下是Swagger2和Swagger3注解的一些主要区别：

通用注解

Swagger2: 使用@Api来注解控制器类，表明该类的路径应该被Swagger文档化。
Swagger3: 不再需要@Api注解。Swagger3使用更自然的方式来扫描类路径，自动包含所有的控制器。

API信息和描述

Swagger2: 通过@ApiInfo和@ApiOperation注解来提供API的信息和操作描述。
Swagger3: 使用@Tag注解来替代@Api，并且通过@Operation注解来提供操作的描述。

路径和操作注解

Swagger2: 使用@ApiOperation来描述一个HTTP操作，@ApiImplicitParam和@ApiImplicitParams用于描述参数。
Swagger3: 引入了@Operation注解来描述HTTP操作，@Parameter注解用于描述参数。

参数注解

Swagger2: 参数注解是通过@ApiParam或@ApiImplicitParam来描述。
Swagger3: 使用@Parameter注解来描述参数，它提供了更丰富的属性，如schema、example和content。

请求体和响应体注解

Swagger2: 使用@ApiModel和@ApiModelProperty注解来描述请求和响应的数据模型。
Swagger3: 引入了@Schema注解来描述数据模型，提供了更多的细节和配置选项。

安全和授权注解

Swagger2: 使用@ApiResponses、@ApiResponse、@ApiOperation等注解来描述响应和错误码。
Swagger3: @ApiResponse注解仍然存在，但是现在可以包含更多的信息，如媒体类型和例子。

详细注解对比

下面我们将详细比较这些注解在Swagger2和Swagger3中的具体使用和区别。

API信息配置

Swagger2

// Swagger2 使用Docket进行配置
@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo());
}

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("My API")
            .description("API Description")
            .version("1.0")
            .build();
}

Swagger3

// Swagger3 使用OpenAPI进行配置
@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                .title("My API")
                .version("2.0")
                .description("API Description")
                .termsOfService("http://swagger.io/terms/")
                .license(new License().name("Apache 2.0").url("http://springdoc.org")));
}

路径和操作注解

Swagger2

@Api(value = "User Management", description = "Operations pertaining to users")
@RestController
@RequestMapping("/users")
public class UserController {

    @ApiOperation(value = "Get a user by ID")
    @RequestMapping(value = "/{userId}", method = RequestMethod.GET)
    public User getUserById(@PathVariable Long userId) {
        // ...
    }
}

Swagger3

@Tag(name = "User Management", description = "Operations pertaining to users")
@RestController
@RequestMapping("/users")
public class UserController {

    @Operation(summary = "Get a user by ID")
    @GetMapping("/{userId}")
    public User getUserById(@PathVariable Long userId) {
        // ...
    }
}

参数注解

Swagger2

public User getUserById(@ApiParam(value = "ID of the user to return", required = true) @PathVariable Long userId) {
    // ...
}

Swagger3

public User getUserById(@Parameter(description = "ID of the user to return", required = true) @PathVariable Long userId) {
    // ...
}

请求体和响应体注解

Swagger2

@ApiModel(description = "User object")
public class User {

    @ApiModelProperty(notes = "The database generated user ID")
    private Long id;

    // ...
}

Swagger3

@Schema(description = "User object")
public class User {

    @Schema(description = "The database generated user ID")
    private Long id;

    // ...
}

安全和授权注解

Swagger2

@ApiOperation(value = "Add a new user", authorizations = {
    @Authorization(value = "apiKey")
})

Swagger3

@Operation(summary = "Add a new user", security = {
    @SecurityRequirement(name = "apiKey")
})

总结

Swagger3（OpenAPI 3）是对Swagger2的一个重大升级，它不仅提供了更多的新特性，也带来了注解的变化。虽然迁移可能需要一些工作，但新的规范和特性是值得的。本文提供了一个基础的迁移指南和注解对比，帮助大家理解如何从Swagger2迁移到Swagger3，并利用它来更好地文档化API。

👉 💐🌸 公众号请关注 "果酱桑", 一起学习,一起进步! 🌸