swagger 一个强大的API文档工具
在spring boot项目中使用也是非常的简单, 简单的记录一下再spring boot项目中的整合方法.
- 引入依赖
xml
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>
- 在需要暴露的类和方法上添加注释
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: 方法级别的注解, 用于描述一个方法的用法和描述信息.
- 配置信息
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/"));
}
}
- 启动项目可以看到配置信息对UI中的影响
4.1 api文档地址: 项目跟路径+ /swagger-ui/index.html
4.2 分组信息:
4.3 项目元数据
4.4 详细的接口信息
- 总结
以上就是spring boot整合swagger的简单用法, 可以看到通过简单的配置, 就可以很方便的使用swagger, 但是也可以看到需要再web类型中加入一些swagger的注解, 对代码也是有一定的入侵的, 如果要使用更多的特性就需要加入更多的注解, 同时对代码的入侵就会更加严重, 在实际使用过程中, 需要开发人员权衡好swagger带来的利弊.
文章这里用的是3.0的版本, 更加明细的用法请参考官方文档: swagger.io/docs/specif...