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支持直接使用接口路径进行配置。

@ConfigurationpublicclassSwaggerConfiguration{@BeanpublicOpenAPIcustomOpenAPI(){returnnewOpenAPI().info(newInfo().title("代码平台 API").description("SpringDoc API 演示").version("v1.0.0"));}@BeanpublicGroupedOpenApiadminApi(){returnGroupedOpenApi.builder().group("普通接口文档").pathsToMatch("/web/test/**").build();}@BeanpublicGroupedOpenApihomeApi(){returnGroupedOpenApi.builder().group("首页相关接口").pathsToMatch("/query/excel/**").build();}

3.常用注解

1.@Tag注解

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

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

2.@Operation注解

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

@Tag(name ="控制器")@RestController@RequestMapping("web/test")publicclassTestController{@Operation(summary ="测试")@RostMapping("test")publicActionResultgetUserInfo(String name){returnActionResult.success(name+"成功");}}

3.@Schema注解

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

例：

@Data@Schema(name="测试")publicclassZnjExpertConsultFastLanguageInsertDTO{@Schema(description="主键id")privateInteger id;}

四、页面访问

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

五、常用配置

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

springdoc:
  swagger-ui:
    # 修改SwaggerUI路径
    path:/swagger-ui.html
    # 开启SwaggerUI界面
    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确实是一个更好的选择。确实很好用，和之前熟悉的用法差不多，

学习成本低

。