这篇文章将介绍如何在 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反对间接应用接口门路进行配置。

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