Springboot微服务项目Swagger接口文档聚合
一.Swagger接口文档单体服务
1.引入jar包
<!--swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2.在微服务中编写swagger2的配置类SwaggerConfig
@Configuration
@EnableSwagger2
public class SwaggerConfig {
private static final String VERSION = "1.0.0";
/**
* 创建API
*/
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//指定接口包所在路径
.apis(RequestHandlerSelectors.basePackage("com.javadaily.product.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 添加摘要信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("product-server接口文档")
.contact(new Contact("JAVA日知录","http://javadaily.cn","jianzh5@163.com"))
.description("product-server接口文档")
.termsOfServiceUrl("http://javadaily.cn")
.license("The Apache License, Version 2.0")
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
.version(VERSION)
.build();
}
}
说明:
.apis方法用于指定生成注解的范围,有以下四种取值逻辑
①RequestHandlerSelectors.any(),为所有接口都生成API文档,这种方式不必在接口上加任何注解,但是生成的文档没有任何注释,可读性不高;
②RequestHandlerSelectors.basePackage(xx.xx),为指定包下的controller生成接口文档
③RequestHandlerSelectors.withClassAnnotation(Api.class),为有@api注解的接口生成api文档
④RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class),为有@ApiOperation注解的方法生成API文档。
给相关接口加上Swagger的注解
打开swagger2接口API页面http://localhost:8020/swagger-ui.html
二.网关聚合(统一网关聚合所有接口)
我们已经给各个微服务加上了api文档,但是每次都需要分别输入各个微服务的文档地址,不太方便。本节内容主要是将各个微服务的api地址聚合到网关层,打开网关的api地址即可查看其它所有服务的接口文档,效果如下:
注意:
它通过配置文件里面的路由id信息进行解析,拿到各个服务的名称
实现步骤如下:;
1…编写配置类实现 SwaggerResourcesProvider 接口聚合其他微服务的api资源
@Component
@AllArgsConstructor
public class CustomSwaggerResourceProvider implements SwaggerResourcesProvider {
/**
* Swagger2默认的url后缀
*/
public static final String SWAGGER2URL = "/v2/api-docs";
/**
* 网关路由
*/
private final RouteLocator routeLocator;
private final GatewayProperties gatewayProperties;
/**
* 聚合其他服务接口
* @return
*/
@Override
public List<SwaggerResource> get() {
List<SwaggerResource> resourceList = new ArrayList<>();
List<String> routes = new ArrayList<>();
//获取网关中配置的route
routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
gatewayProperties.getRoutes().stream().filter(routeDefinition -> routes.contains(routeDefinition.getId()))
.forEach(routeDefinition -> routeDefinition.getPredicates().stream()
.filter(predicateDefinition -> "Path".equalsIgnoreCase(predicateDefinition.getName()))
.forEach(predicateDefinition -> resourceList.add(
swaggerResource(
routeDefinition.getId(),
predicateDefinition
.getArgs()
.get(NameUtils.GENERATED_NAME_PREFIX + "0")
.replace("/**",SWAGGER2URL)
//这里拼接时需要注意
//网关配置account映射到account-service,要么将网关的配置修改成account-service映射成account-service
//要么就在这个拼接处解决
)
)));
return resourceList;
}
private SwaggerResource swaggerResource(String name, String location) {
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setName(name);
swaggerResource.setLocation(location);
swaggerResource.setSwaggerVersion("2.0");
return swaggerResource;
}
}
- 自定义Rest接口。
@RestController
@RequestMapping("/swagger-resources")
public class SwaggerHandler {
@Autowired(required = false)
private SecurityConfiguration securityConfiguration;
@Autowired(required = false)
private UiConfiguration uiConfiguration;
private final SwaggerResourcesProvider swaggerResources;
@Autowired
public SwaggerHandler(SwaggerResourcesProvider swaggerResources) {
this.swaggerResources = swaggerResources;
}
@GetMapping("/configuration/security")
public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {
return Mono.just(new ResponseEntity<>(
Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));
}
@GetMapping("/configuration/ui")
public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {
return Mono.just(new ResponseEntity<>(
Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()),HttpStatus.OK));
}
@GetMapping("")
public Mono<ResponseEntity> swaggerResources() {
return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
}
}
参考链接: link.