这篇文章将介绍如何在 java 中使用 swagger3,

文章目录

• 一、Swagger3 简介
• 二、与Swagger2注解对比
• 三、 使用步骤
• • 1.导入依赖
  • 2.添加配置类
  • 3.常用注解
  • • 1.@Tag注解
    • 2.@Operation注解
    • 3.@Schema注解
    • 四、页面访问
    • 五、常用配置
    • 六、总结

      一、Swagger3 简介

      官网地址:https://swagger.io/

      

      Swagger 是一个规范和完整的框架，用于生成可视化 RESTful 风格的 Web 服务。是一个简单且功能强大的API工具。几乎所有的现代编程语言，都在支持和使用。

      Swagger2已经停止维护了，取而代之的是 swagger3，

      二、与Swagger2注解对比

      之前在SpringBoot项目中一直使用的是SpringFox提供的Swagger库,已经很久没有更新了。

      SpringDoc是一款可以结合SpringBoot使用的API文档生成工具，基于OpenAPI 3,

      是一款更好用的Swagger库！值得一提的是SpringDoc不仅支持Spring WebMvc项目，还可以支持Spring WebFlux项目，甚至Spring Rest和Spring Native项目，总之非常强大

      经常使用的Swagger注解，看看SpringFox的和SpringDoc的有啥区别，毕竟对比已学过的技术能更快掌握新技术;

      

      三、 使用步骤

      1.导入依赖

         
             org.springdoc
             springdoc-openapi-ui
             1.5.10
         
      

      2.添加配置类

      进行SpringDoc的配置，使用OpenAPI来配置基础的文档信息，通过GroupedOpenApi配置分组的API文档，SpringDoc支持直接使用接口路径进行配置。

      @Configuration
      public class SwaggerConfiguration {
          @Bean
          public OpenAPI customOpenAPI() {
              return new OpenAPI().info(new Info()
                      .title("代码平台 API")
                      .description("SpringDoc API 演示")
                      .version("v1.0.0")
              );
          }
          @Bean
          public GroupedOpenApi adminApi() {
              return GroupedOpenApi.builder()
                      .group("普通接口文档")
                      .pathsToMatch("/web/test/**").build();
          }
          @Bean
          public GroupedOpenApi homeApi() {
              return GroupedOpenApi.builder()
                      .group("首页相关接口")
                      .pathsToMatch("/query/excel/**")
                      .build();
          }
      

      3.常用注解

      1.@Tag注解

      用来描述一组操作的信息（通常用在controller控制层类上）

      例：

      @Tag(name = "控制器")
      @RestController
      @RequestMapping("web/test")
      public class TestController {
      }
      

      2.@Operation注解

      用来描述接口信息（通常用在控制层的具体方法上）

      例：

      @Tag(name = "控制器")
      @RestController
      @RequestMapping("web/test")
      public class TestController {
          @Operation(summary = "测试")
          @RostMapping("test")
          public ActionResult getUserInfo(String name) {
              return ActionResult.success(name+"成功");
          }
      }
      

      3.@Schema注解

      该注解用来定义模型及模型的属性（可以用在dto/vo以及其属性上）

      

      例：

      @Data
      @Schema(name= "测试")
      public class ZnjExpertConsultFastLanguageInsertDTO {
          @Schema(description="主键id")
          private Integer id;
      }
      

      四、页面访问

      http://ip:port/swagger-ui.html

      

      五、常用配置

      SpringDoc还有一些常用的配置可以了解下。

      springdoc:
        swagger-ui:
          # 修改Swagger UI路径
          path: /swagger-ui.html
          # 开启Swagger UI界面
          enabled: true
        api-docs:
          # 修改api-docs路径
          path: /v3/api-docs
          # 开启api-docs
          enabled: true
        # 配置需要生成接口文档的扫描包
        packages-to-scan: com.test.controller
        # 配置需要生成接口文档的接口路径
        paths-to-match: /web/test/**,/query/excel/**
      

      六、总结

      迁移到SpringDoc确实是一个更好的选择。确实很好用，和之前熟悉的用法差不多，学习成本低。

       
       企业网站建设规划  情书网站制作  检测网站是否安全  免费设计logo生成器  中山网站建设  北京营销型网站设计