Hexo

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

官方文档

一、引入依赖

language-xml

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

language-yml

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

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

language-html

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

二、使用

1. @OpenAPIDefinition + @Info

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

language-java

@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 进行分组。可以在控制器类或方法级别上使用。

language-java

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

3. @Operation

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

language-java

@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

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

language-java

@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

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

language-java

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

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

6. @ApiResponse

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

language-java

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