SpringBoot3整合OpenAPI3(Swagger3)

swagger2更新到3后，再使用方法上发生了很大的变化，名称也变为OpenAPI3。

官方文档

一、引入依赖

            <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>${springdoc-openapi.version}</version></dependency>

server:servlet:context-path: /content
springdoc:api-docs:enabled: truepath: /v3/api-docsswagger-ui:enabled: truepath: /swagger-ui.html

openapi3使用十分方便，做到这里后，你可以直接通过以下网址访问swagger页面。

http://<ip>:<port>/content/swagger-ui/index.html

二、使用

1. @OpenAPIDefinition + @Info

用于定义整个 API 的信息，通常放在主应用类上。可以包括 API 的标题、描述、版本等信息。

@SpringBootApplication
@Slf4j
@OpenAPIDefinition(info = @Info(title = "内容管理系统", description = "对课程相关信息进行管理", version = "1.0.0"))
public class ContentApplication {public static void main(String[] args) {SpringApplication.run(ContentApplication.class, args);}
}

2. @Tag

用于对 API 进行分组。可以在控制器类或方法级别上使用。

@Tag(name = "课程信息编辑接口")
@RestController("content")
public class CourseBaseInfoController {
}

3. @Operation

描述单个 API 操作（即一个请求映射方法）。可以提供操作的摘要、描述、标签等。

    @Operation(summary = "课程查询接口")@PostMapping("/course/list")public PageResult<CourseBase> list(PageParams params,@RequestBody(required = false) QueryCourseParamsDto dto){CourseBase courseBase = new CourseBase();courseBase.setCreateDate(LocalDateTime.now());return new PageResult<CourseBase>(new ArrayList<CourseBase>(List.of(courseBase)),20, 2, 10);}

4. @Parameter

用于描述方法参数的额外信息，例如参数的描述、是否必需等。

    @Operation(summary = "课程查询接口")@PostMapping("/course/list")public PageResult<CourseBase> list(@Parameter(description = "分页参数") PageParams params,@Parameter(description = "请求具体内容") @RequestBody(required = false) QueryCourseParamsDto dto){CourseBase courseBase = new CourseBase();courseBase.setCreateDate(LocalDateTime.now());return new PageResult<CourseBase>(new ArrayList<CourseBase>(List.of(courseBase)),20, 2, 10);}

5. @Schema

描述模型的结构。可以用于类级别（标注在模型类上）或字段级别。

@Data
@AllArgsConstructor
@NoArgsConstructor
public class PageParams {//当前页码@Schema(description = "页码")private Long pageNo = 1L;//每页记录数默认值@Schema(description = "每页条目数量")private Long pageSize =10L;
}

6. @ApiResponse

描述 API 响应的预期结果。可以指定状态码、描述以及返回类型。

@ApiResponse(responseCode = "200", description = "Successfully retrieved user")
public User getUserById(@PathVariable Long id) {
}