Swagger3 使用介绍 迁移到SpringDoc确实是一个更好的选择。确实很好用,和之前熟悉的用法差不多,学习成本低。
这篇文章将介绍如何在 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.导入依赖
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确实是一个更好的选择。确实很好用,和之前熟悉的用法差不多,
学习成本低
。
Swagger3 使用介绍 迁移到SpringDoc确实是一个更好的选择。确实很好用,和之前熟悉的用法差不多,学习成本低。Swagger3 使用介绍 迁移到SpringDoc确实是一个更好的选择。确实很好用,和之前熟悉的用法差不多,学习成本低。Swagger3 使用介绍 迁移到SpringDoc确实是一个更好的选择。确实很好用,和之前熟悉的用法差不多,学习成本低。Swagger3 使用介绍 迁移到SpringDoc确实是一个更好的选择。确实很好用,和之前熟悉的用法差不多,学习成本低。Swagger3 使用介绍 迁移到SpringDoc确实是一个更好的选择。确实很好用,和之前熟悉的用法差不多,学习成本低。Swagger3 使用介绍 迁移到SpringDoc确实是一个更好的选择。确实很好用,和之前熟悉的用法差不多,学习成本低。Swagger3 使用介绍 迁移到SpringDoc确实是一个更好的选择。确实很好用,和之前熟悉的用法差不多,学习成本低。Swagger3 使用介绍 迁移到SpringDoc确实是一个更好的选择。确实很好用,和之前熟悉的用法差不多,学习成本低。Swagger3 使用介绍 迁移到SpringDoc确实是一个更好的选择。确实很好用,和之前熟悉的用法差不多,学习成本低。