swagger2和swagger3使用区别

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful Web服务。
Swagger2是Swagger规范的一个实现，而Swagger3是基于OpenAPI规范的新版本，它是Swagger规范的后续标准，
提供了更好的可扩展性和更丰富的功能。

Spring Boot从2.6.0版本开始不再原生支持Swagger2，因为Spring官方的更新导致了与Swagger2的不兼容。
开发者需要使用Springdoc OpenAPI库来替代Springfox，以在Spring Boot 2.6.0及以上版本中集成OpenAPI文档。
Springdoc OpenAPI提供了对OpenAPI 3.0规范的支持，并且与Spring Boot的新版本兼容。

1.引入依赖不同

swagger2

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

swagger3

<dependencys>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-webmvc-core</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-security</artifactId>
    </dependency>
    <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-annotations</artifactId>
    </dependency>
</dependencys>

2.使用时注解不同

位置	swagger2	swagger3
controller类上	@Api	@Tag
controller方法(接口)上	@ApiOperation	@Operation
controller方法参数上（一般get请求参数在这里）	@ApiImplicitParams、@ApiImplicitParam	@Parameters、@Parameter
post请求参数类上（一般在body中）	@ApiModel	@Schema
post请求参数类属性上（一般在body中）	@ApiModelProperty	@Schema
返回值类上	@ApiModel	@Schema
返回值类属性上	@ApiModelProperty	@Schema

代码示例：

swagger2

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;

// PostParam.java
@ApiModel(value = "post请求参数")
public class PostParam {

    @ApiModelProperty(value = "参数1", required = true)
    private String param1;

}

// XxxController.java
@Api(tags = "controller名称", description = "controller描述")
public class XxxController {

    @ApiImplicitParams({
            @ApiImplicitParam(name = "param1", value = "参数1", required = true, dataType = "String")
    })
    @ApiOperation("get请求（接口汉字描述）")
    // 只有一个参数也可以直接写里面的 @ApiImplicitParam
    // @ApiImplicitParam(name = "param1", value = "参数1", required = true, dataType = "String")
    @GetMapping("/query")
    public Result<String> query(String param1) {
        return null;
    }

    @ApiOperation("post请求（接口汉字描述）")
    @PostMapping("/post")
    public Result<String> post(@RequestBody PostParam postParam) {
        return null;
    }
}

swagger3

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import io.swagger.v3.oas.annotations.media.Schema;

// PostParam.java
@Schema(title = "post请求参数")
public class PostParam {

    @Schema(description = "参数1", required = true)
    private String param1;

}

// XxxController.java
@Tag(name = "controller名称", description = "controller描述")
public class XxxController {

    @Parameters({
            @Parameter(name = "param1", description = "参数1", required = true)
    })
    @Operation(summary = "get请求（接口汉字描述）")
    // 只有一个参数也可以直接写里面的 @ApiImplicitParam
    // @Parameter(name = "param1", description = "参数1", required = true)
    @GetMapping("/query")
    public Result<String> query(String param1) {
        return null;
    }

    @Operation(summary = "post请求（接口汉字描述）")
    @PostMapping("/post")
    public Result<String> post(@RequestBody PostParam postParam) {
        return null;
    }
}

如果get请求需要用对象接收多个字段，在接口方法参数用@ParameterObject注解，
并在类上加@Schema注解、字段上加上@Parameter注解。

示例：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springdoc.api.annotations.ParameterObject;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import io.swagger.v3.oas.annotations.media.Schema;

// GetParam.java
@Schema(title = "get请求参数")
public class GetParam {

    @Parameter(description = "参数1", required = true)
    private String param1;

}

// XxxController.java
@Tag(name = "controller名称", description = "controller描述")
public class XxxController {

    @Operation(summary = "get请求（接口汉字描述）")
    @GetMapping("/query")
    public Result<String> query(@ParameterObject GetParam param) {
        return null;
    }
}