文章目录

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

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

      官方文档

      一、引入依赖

                  
                      org.springdoc
                      springdoc-openapi-starter-webmvc-ui
                      ${springdoc-openapi.version}
                  
      

      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://:/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 list(
                  PageParams params,
                  @RequestBody(required = false) QueryCourseParamsDto dto){
              CourseBase courseBase = new CourseBase();
              courseBase.setCreateDate(LocalDateTime.now());
              return new PageResult(new ArrayList(List.of(courseBase)),20, 2, 10);
          }
      

      

      4. @Parameter

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

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

      

       
       网络app制作  免费ppt  自己免费做网站  整合营销  沙河网站建设公司  房产网站系统