SpringBoot3整合OpenAPI3(Swagger3)

文章目录

  • 一、引入依赖
  • 二、使用
      • 1. @OpenAPIDefinition + @Info
      • 2. @Tag
      • 3. @Operation
      • 4. @Parameter
      • 5. @Schema
      • 6. @ApiResponse

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

官方文档

一、引入依赖

            <dependency>
                <groupId>org.springdocgroupId>
                <artifactId>springdoc-openapi-starter-webmvc-uiartifactId>
                <version>${springdoc-openapi.version}version>
            dependency>
server:
  servlet:
    context-path: /content
springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html

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

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

SpringBoot3整合OpenAPI3(Swagger3)_第1张图片

二、使用

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

SpringBoot3整合OpenAPI3(Swagger3)_第2张图片

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

SpringBoot3整合OpenAPI3(Swagger3)_第3张图片

5. @Schema

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

@Data
@AllArgsConstructor
@NoArgsConstructor
public class PageParams {
    //当前页码
    @Schema(description = "页码")
    private Long pageNo = 1L;

    //每页记录数默认值
    @Schema(description = "每页条目数量")
    private Long pageSize =10L;
}

SpringBoot3整合OpenAPI3(Swagger3)_第4张图片

6. @ApiResponse

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

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

SpringBoot3整合OpenAPI3(Swagger3)_第5张图片

你可能感兴趣的:(#,OpenAPI3,SpringBoot3,postman,java,springboot)