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;
}
}