SpringBoot整合Swagger3

swagger 一个强大的API文档工具

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

1. 引入依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>

2. 在需要暴露的类和方法上添加注解

@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();
    }
}

@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();
    }
}

@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: 方法级别的注解, 用于描述一个方法的用法和描述信息.

3. 配置信息

@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/"));
    }
}

4. 启动项目可以看到配置信息对UI中的影响

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

4.2 分组信息:

4.3 项目元数据

4.4 详细的接口信息

5. 总结

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

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