关于java:Swagger3-使用介绍

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

一、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. 导入依赖

   <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-ui</artifactId>
       <version>1.5.10</version>
   </dependency>

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 的确是一个更好的抉择。的确很好用，和之前相熟的用法差不多，学习成本低。