Autor: macrozheng
Enlace original: https://mp.weixin.qq.com/s/4LK0Hs15nHlSOzXG4h149w
Recuerde que en mi proyecto de microservicio mall-swarm, no hay agregación de documentos de API. Para acceder al documento de API de cada servicio, debe acceder a una página swagger-ui.html separada. Como usamos microservicios, deberíamos tener un documento de API unificado. Entrada, recientemente descubrí que knife4j tiene soporte en esta área. Este artículo presentará su implementación en detalle, ¡espero que sea útil para todos!
Conocimiento previo
Usaremos Nacos como centro de registro, Gateway como puerta de enlace y knife4j para generar documentación API.
Arquitectura de la aplicación
Nuestra solución ideal debería ser así: la puerta de enlace sirve como un punto de entrada unificado para los documentos de la API. La puerta de enlace agrega los documentos de todos los microservicios y logra el acceso a otros documentos de la API de servicio al cambiar en la puerta de enlace.
División de servicios relacionados:
- micro-knife4j-gateway: servicio de puerta de enlace, como entrada de acceso para documentos de API de microservicio, agrega todos los documentos de API y necesita introducir el paquete de interfaz de usuario de interfaz de usuario de documentos;
- micro-knife4j-user: servicio de usuario, servicio de API común, no es necesario introducir un paquete de interfaz de usuario de documento;
- micro-knife4j-order: servicio de pedidos, servicio de API común, no es necesario introducir el paquete de interfaz de usuario de documento.
Implementación
La siguiente es una introducción detallada a la implementación del documento de API de agregación Spring Cloud Gateway + knife4j y, a su vez, crea el servicio de usuario, el servicio de pedidos y el servicio de pasarela.
micro-cuchillo4j-usuario
Primero construyamos un servicio de usuario, un servicio de API común, que es muy simple y solo se necesitan tres pasos para integrar knife4j.
- Agregue dependencias relacionadas en pom.xml, una dependencia de función web SpringBoot, dependencia de microservicio de knife4j (paquete de interfaz de usuario de front-end que no incluye documentación de API);
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-micro-spring-boot-starter</artifactId>
</dependency>
</dependencies>- Agregue la configuración relevante en application.yml y configure el registro de Nacos;
server:
port: 9501
spring:
profiles:
active: dev
application:
name: micro-knife4j-user
cloud:
nacos:
discovery:
server-addr: localhost:8848
management:
endpoints:
web:
exposure:
include: "*"- Agregue la configuración relacionada con Swagger, configuración muy convencional, agregue la anotación @ EnableKnife4j para habilitar la función mejorada de knife4j.
/**
* Swagger API相关配置
*/
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {
@Bean
public Docket createRestApi(){ return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.macro.cloud.controller"))
.paths(PathSelectors.any())
.build();
} private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("micro-knife4j-user")
.description("用户服务API文档")
.contact("macro")
.version("1.0")
.build();
}}micro-cuchillo
A continuación, crearemos un servicio de pedidos, un servicio API común, solo consulte la configuración del servicio de usuario anterior.
puerta de enlace micro-knife4j
Finalmente, creamos un servicio de puerta de enlace, que sirve como un punto de entrada unificado para los documentos de la API de microservicio y agrega todos los documentos de la API de microservicio.
- Agregue dependencias relacionadas en pom.xml, dependencias relacionadas con Gateway y knife4j Starter (paquete de interfaz de usuario que contiene documentación API);
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>
</dependencies>- Agregue la configuración relevante en application.yml, configure la ruta del registro de Nacos, el servicio al usuario y el servicio de pedidos;
server:
port: 9201
spring:
profiles:
active: dev
application:
name: micro-knife4j-gateway
cloud:
nacos:
discovery:
server-addr: localhost:8848
gateway:
routes: #配置路由路径
- id: user-service
uri: lb://micro-knife4j-user
predicates:
- Path=/user-service/**
filters:
- StripPrefix=1
- id: order-service
uri: lb://micro-knife4j-order
predicates:
- Path=/order-service/**
filters:
- StripPrefix=1
discovery:
locator:
enabled: true #开启从注册中心动态创建路由的功能
lower-case-service-id: true #使用小写服务名，默认是大写- Agregue la configuración de recursos Swagger en la puerta de enlace para agregar la ruta de acceso api-docs de Swagger en otros microservicios;
/**
* Swagger资源配置
* Created by macro on 2020/7/9.
*/
@Slf4j
@Component
@Primary
@AllArgsConstructor
public class SwaggerResourceConfig implements SwaggerResourcesProvider {
private final RouteLocator routeLocator;
private final GatewayProperties gatewayProperties;
@Override
public List<SwaggerResource> get() {
List<SwaggerResource> resources = new ArrayList<>();
List<String> routes = new ArrayList<>();
//获取所有路由的ID
routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
//过滤出配置文件中定义的路由->过滤出Path Route Predicate->根据路径拼接成api-docs路径->生成SwaggerResource
gatewayProperties.getRoutes().stream().filter(routeDefinition -> routes.contains(routeDefinition.getId())).forEach(route -> {
route.getPredicates().stream()
.filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))
.forEach(predicateDefinition -> resources.add(swaggerResource(route.getId(),
predicateDefinition.getArgs().get(NameUtils.GENERATED_NAME_PREFIX + "0")
.replace("**", "v2/api-docs"))));
});
return resources;
}
private SwaggerResource swaggerResource(String name, String location) {
log.info("name:{},location:{}", name, location);
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setName(name);
swaggerResource.setLocation(location);
swaggerResource.setSwaggerVersion("2.0");
return swaggerResource;
}
}- ¿Cuál es la ruta de acceso de los api-docs de Swagger? Esta ruta devolverá datos en formato JSON, y todos los datos de la página del documento de la API de renderizado Swagger provienen de esta. Por ejemplo, nuestro servicio de usuario devolverá la siguiente información, dirección de acceso: http: // localhost: 9201 / user-service / v2 / api- docs
- A continuación, necesitamos personalizar los nodos de cada configuración de Swagger, que es simplemente personalizar las interfaces para obtener datos dentro de Swagger;
/**
* 自定义Swagger的各个配置节点
* Created by macro on 2020/7/9.
*/
@RestController
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;
} /**
* Swagger安全配置，支持oauth和apiKey设置
*/
@GetMapping("/swagger-resources/configuration/security")
public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {
return Mono.just(new ResponseEntity<>(
Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK)); } /**
* Swagger UI配置
*/
@GetMapping("/swagger-resources/configuration/ui")
public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {
return Mono.just(new ResponseEntity<>(
Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()), HttpStatus.OK)); } /**
* Swagger资源配置，微服务中这各个服务的api-docs信息
*/
@GetMapping("/swagger-resources")
public Mono<ResponseEntity> swaggerResources() {
return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
}}- Por ejemplo, la interfaz swagger-resources se puede utilizar para obtener la ruta de acceso api-docs de todos los microservicios. La información de acceso es la siguiente, la dirección de acceso: http: // localhost: 9201 / swagger-resources
Manifestación
A continuación, demostraremos la función de agregación de documentos de API de microservicio. Solo necesita acceder a la página de documentos de API de la puerta de enlace y puede cambiar al documento de API del servicio correspondiente usted mismo.
- Antes de eso, inicie primero nuestro registro de Nacos, y luego inicie los servicios micro-knife4j-user, micro-knife4j-order y micro-knife4j-gateway;
- Acceda al documento API desde la puerta de enlace, dirección de acceso: http: // localhost: 9201 / doc.html
- Podemos cambiar al documento API del servicio correspondiente a través del componente de cambio en la esquina superior izquierda;
- Al observar la documentación de la API, podemos encontrar que todas las interfaces se han agregado con los prefijos de acceso correspondientes y se puede acceder normalmente.
Volver a la interfaz de usuario de Swagger
Si no desea utilizar la interfaz de knife4j, pero desea utilizar la interfaz Swagger original, también es compatible.El método de cambio es muy simple, hablemos de ello a continuación.
- En primer lugar, necesitamos eliminar las dependencias relevantes de knife4j en pom.xml, principalmente las siguientes dos dependencias;
<dependencies>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-micro-spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>
</dependencies>- Agregue las dependencias relacionadas con Swagger en pom.xml y elimine la anotación original @ EnableKnife4j;
<dependencies>
<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>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.6.0</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.6.0</version>
</dependency>
</dependencies>- Reinicie todos los servicios y acceda a la ruta del documento API de la puerta de enlace para ver: http: // localhost: 9201 / swagger-ui.html
para resumir
Al comparar el uso de microservicios entre knife4j y Swagger nativo, demuestra una vez más que knife4j es una implementación mejorada de la interfaz de usuario de springfox-swagger, que sigue completamente la forma de usar springfox-swagger.
Referencia
Documento oficial: https://doc.xiaominfo.com/guide/ui-front-gateway.html
Dirección de origen del proyecto
https://github.com/macrozheng/springcloud-learning/tree/master/micro-knife4j