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

  • 24
    点赞
  • 59
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 3
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论 3
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

Dream_sky分享

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值