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...

相关推荐
RestCloud5 小时前
数据传输中的三大难题,ETL 平台是如何解决的?
数据分析·api
RestCloud5 小时前
为什么说 iPaaS 是企业数字化转型的加速器?
api
xiezhr15 小时前
用户只需要知道「怎么办」,不需要知道「为什么炸了」
java·api·接口设计规范
xiezhr15 小时前
接口设计18条军规:写给那些半夜被“502”叫醒的人
java·api·restful
用户268001379191 天前
多语言采集京东商品评论,京东API(json数据返回)
api
RestCloud1 天前
SQL Server到Hive:批处理ETL性能提升30%的实战经验
数据库·api
RestCloud1 天前
为什么说零代码 ETL 是未来趋势?
数据库·api
RestCloud2 天前
跨境数据传输:ETL如何处理时区与日期格式差异
mysql·api
RestCloud2 天前
揭秘 CDC 技术:让数据库同步快人一步
数据库·api
用户268001379192 天前
Python采集tiktok视频详情数据,tiktok API系列
api