SpringBoot整合Swagger3

swagger 一个强大的API文档工具

在spring boot项目中使用也是非常的简单, 简单的记录一下再spring boot项目中的整合方法.

  1. 引入依赖
xml 复制代码
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>
  1. 在需要暴露的类和方法上添加注释
less 复制代码
@RestController
@RequestMapping("/demo")
@Tag(name = "Demo接口", description = "Demo接口描述信息")
public class DemoController {

    @GetMapping("/01")
    @Operation(summary = "Demo接口01", description = "Demo接口01描述信息")
    public CarInfo test() {
        return new CarInfo();
    }

    @GetMapping("/02")
    @Operation(summary = "Demo接口02", description = "Demo接口02描述信息")
    public CarInfo test02() {
        return new CarInfo();
    }
}
less 复制代码
@RestController
@RequestMapping("/test")
@Tag(name = "测试接口", description = "测试接口描述信息")
public class TestController {

    @GetMapping("/01")
    @Operation(summary = "测试接口01", description = "测试接口01描述信息")
    public CarInfo test() {
        return new CarInfo();
    }

    @GetMapping("/02")
    @Operation(summary = "测试接口02", description = "测试接口02描述信息")
    public CarInfo test02() {
        return new CarInfo();
    }
}
less 复制代码
@RestController
@RequestMapping("/test02")
@Tag(name = "测试接口", description = "测试接口描述信息2")
public class Test02Controller {

    @GetMapping("/01")
    @Operation(summary = "测试接口01", description = "测试接口01描述信息")
    public CarInfo test() {
        return new CarInfo();
    }

    @GetMapping("/02")
    @Operation(summary = "测试接口02", description = "测试接口02描述信息")
    public CarInfo test02() {
        return new CarInfo();
    }
}

这里用到了两个相关注解:

@Tag: 写在类上, 如果多个类使用同一个name, 例如: TestController和Test02Controller 在最终的展示页面, 这两个类的接口会被划分到一个列表内展示.

@Operation: 方法级别的注解, 用于描述一个方法的用法和描述信息.

  1. 配置信息
java 复制代码
@Configuration
public class Swagger3Config {

    @Bean
    public GroupedOpenApi testApi()
    {
        return GroupedOpenApi.builder().group("测试模块").pathsToMatch("/**").build();
    }
    @Bean
    public GroupedOpenApi otherApi()
    {
        return GroupedOpenApi.builder().group("其它微服务模块").pathsToMatch("/other/**", "/others").build();
    }

    @Bean
    public GroupedOpenApi commonApi()
    {
        return GroupedOpenApi.builder().group("通用服务模块").pathsToMatch("/common/**").build();
    }

    @Bean
    public OpenAPI docsOpenApi()
    {
        return new OpenAPI()
            .info(new Info().title("winston的swagger3学习")
                      .description("winston的swagger3学习, 必将学习成为大牛")
                      .version("v1.0"))
            .externalDocs(new ExternalDocumentation()
                              .description("百度一下,你就知道")
                              .url("https://www.baidu.com/"));
    }
}
  1. 启动项目可以看到配置信息对UI中的影响

4.1 api文档地址: 项目跟路径+ /swagger-ui/index.html

4.2 分组信息:

4.3 项目元数据

4.4 详细的接口信息

  1. 总结

以上就是spring boot整合swagger的简单用法, 可以看到通过简单的配置, 就可以很方便的使用swagger, 但是也可以看到需要再web类型中加入一些swagger的注解, 对代码也是有一定的入侵的, 如果要使用更多的特性就需要加入更多的注解, 同时对代码的入侵就会更加严重, 在实际使用过程中, 需要开发人员权衡好swagger带来的利弊.

文章这里用的是3.0的版本, 更加明细的用法请参考官方文档: swagger.io/docs/specif...

相关推荐
lichong95111 小时前
API开发工具postman、国内xxapi和SmartApi的性能对比
eclipse·intellij-idea·api·postman·visual studio·apipost·apifox
RestCloud1 天前
从MySQL到StarRocks:全量与增量同步的最佳实践
数据库·mysql·api
RestCloud2 天前
PostgreSQL大表同步优化:如何避免网络和内存瓶颈?
前端·数据库·api
用户268001379192 天前
淘宝评论API获取JSON数据全流程指南
api
RestCloud3 天前
数据集成平台怎么选?从ETL到CDC再到iPaaS的全景对比
api
RestCloud3 天前
企业为什么需要一款 ETL 集成平台?五大痛点解析
api
蓝倾3 天前
利用API接口合规获取淘宝店铺所有商品实战案例(2025年最新版)
api·fastapi
小豆包api4 天前
小豆包AI API × Nano Banana:3D手办 + AI视频生成,「动起来」的神级玩法!
前端·api
RestCloud4 天前
iPaaS 如何帮助 CIO 减少 50% 的集成成本?
api
RestCloud4 天前
零代码集成真的靠谱吗?ETL平台的背后技术揭秘
api