Autor: macrozheng
Ursprünglicher Link: https://mp.weixin.qq.com/s/4LK0Hs15nHlSOzXG4h149w
Denken Sie daran, dass es in meinem mall-swarm-Microservice-Projekt keine API-Dokumentaggregation gibt. Um auf das API-Dokument jedes Service zugreifen zu können, müssen Sie auf eine separate swagger-ui.html-Seite zugreifen. Da wir Microservices verwenden, sollten wir ein einheitliches API-Dokument haben. Eingang, ich habe kürzlich festgestellt, dass Messer4j Unterstützung in diesem Bereich hat. Dieser Artikel wird seine Implementierung im Detail vorstellen, ich hoffe, es wird für alle hilfreich sein!
Vorkenntnisse
Wir werden Nacos als Registrierungscenter, Gateway als Gateway und Messer4j verwenden, um API-Dokumentation zu generieren
Anwendungsarchitektur
Unsere ideale Lösung sollte folgendermaßen aussehen: Das Gateway dient als einheitlicher Einstiegspunkt für API-Dokumente. Das Gateway fasst die Dokumente aller Microservices zusammen und ermöglicht den Zugriff auf andere Service-API-Dokumente, indem es am Gateway wechselt.
Verwandte Serviceabteilung:
- micro -esser4j-gateway: Der Gateway-Dienst als Zugriffseintrag für Microservice-API-Dokumente aggregiert alle API-Dokumente und muss das Dokument-Front-End-UI-Paket einführen.
- micro -messer4j-user: Benutzerdienst, allgemeiner API-Dienst, keine Notwendigkeit, ein Dokument-Front-End-UI-Paket einzuführen;
- micro -messer4j-order: Bestellservice, allgemeiner API-Service, keine Notwendigkeit, ein Front-End-UI-Paket für Dokumente einzuführen.
Implementierung
Im Folgenden finden Sie eine detaillierte Einführung in die Implementierung des Aggregations-API-Dokuments Spring Cloud Gateway + Messer4j, in dem der Benutzerservice, der Bestellservice und der Gateway-Service nacheinander erstellt werden.
micro-messer4j-user
Lassen Sie uns zunächst einen Benutzerdienst erstellen, einen allgemeinen API-Dienst, der sehr einfach ist und für die Integration vonmesser4j nur drei Schritte benötigt.
- Fügen Sie verwandte Abhängigkeiten in pom.xml hinzu, eine SpringBoot-Webfunktionsabhängigkeit und eine Messer4j-Mikroservice-Abhängigkeit (Front-End-UI-Paket ohne API-Dokumentation).
<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>- Fügen Sie die entsprechende Konfiguration in application.yml hinzu und konfigurieren Sie die Nacos-Registrierung.
server:
port: 9501
spring:
profiles:
active: dev
application:
name: micro-knife4j-user
cloud:
nacos:
discovery:
server-addr: localhost:8848
management:
endpoints:
web:
exposure:
include: "*"- Fügen Sie eine Swagger-bezogene Konfiguration hinzu, eine sehr konventionelle Konfiguration, und fügen Sie die Annotation @ EnableKnife4j hinzu, um die erweiterte Funktion von Messer4j zu aktivieren.
/**
* 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();
}}Mikromesser4j-Bestellung
Als Nächstes erstellen wir einen Bestellservice, einen allgemeinen API-Service. Weitere Informationen finden Sie im obigen Setup für den Benutzerservice.
Mikromesser4j-Gateway
Schließlich erstellen wir einen Gateway-Service, der als einheitlicher Einstiegspunkt für die Microservice-API-Dokumente dient und alle Microservice-API-Dokumente aggregiert.
- Fügen Sie verwandte Abhängigkeiten in pom.xml, Gateway-bezogene Abhängigkeiten und Messer4j Starter (Front-End-UI-Paket mit API-Dokumentation) hinzu.
<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>- Fügen Sie die relevante Konfiguration in application.yml hinzu und konfigurieren Sie die Route der Nacos-Registrierung, des Benutzerservices und des Bestellservices.
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 #使用小写服务名，默认是大写- Fügen Sie die Swagger-Ressourcenkonfiguration auf dem Gateway hinzu, um den API-Docs-Zugriffspfad von Swagger in anderen Microservices zusammenzufassen.
/**
* 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;
}
}- Was ist der Zugriffspfad von Swaggers API-Dokumenten? Dieser Pfad gibt Daten im JSON-Format zurück, und alle Daten der Swagger-Rendering-API-Dokumentseite stammen von diesem. Beispielsweise gibt unser Benutzerdienst die folgenden Informationen zurück: Zugriffsadresse: http: // localhost: 9201 / user-service / v2 / api- docs
- Als nächstes müssen wir die Knoten jeder Konfiguration von Swagger anpassen, dh einfach die Schnittstellen anpassen, um Daten in Swagger zu erhalten.
/**
* 自定义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)));
}}- Beispielsweise kann die Swagger-Resources-Schnittstelle verwendet werden, um den API-Docs-Zugriffspfad aller Microservices abzurufen. Die Zugriffsinformationen lauten wie folgt: http: // localhost: 9201 / swagger-resources
Demo
Als Nächstes werden wir die Funktion der Aggregation von Microservice-API-Dokumenten demonstrieren. Sie müssen nur auf die API-Dokumentenseite des Gateways zugreifen und können selbst zum API-Dokument des jeweiligen Dienstes wechseln.
- Starten Sie vorher zuerst unsere Nacos-Registrierung und starten Sie dann nacheinander die Dienste micro -messer4j-user, micro-messer4j-order und micro-messer4j-gateway.
- Greifen Sie über das Gateway auf das API-Dokument zu. Zugriffsadresse: http: // localhost: 9201 / doc.html
- Wir können über die Switch-Komponente in der oberen linken Ecke zum API-Dokument des entsprechenden Dienstes wechseln.
- In der API-Dokumentation können wir feststellen, dass alle Schnittstellen mit entsprechenden Zugriffspräfixen hinzugefügt wurden und normal aufgerufen werden können.
Wechseln Sie zurück zur Swagger-Benutzeroberfläche
Wenn Sie die Messer4j-Schnittstelle nicht verwenden möchten, aber die ursprüngliche Swagger-Schnittstelle verwenden möchten, wird diese ebenfalls unterstützt. Die Umschaltmethode ist sehr einfach. Lassen Sie uns weiter unten darauf eingehen.
- Zunächst müssen wir die relevanten Abhängigkeiten von Messer4j in pom.xml entfernen, hauptsächlich die folgenden zwei Abhängigkeiten;
<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>- Fügen Sie Swagger-bezogene Abhängigkeiten in pom.xml hinzu und entfernen Sie die ursprüngliche @ EnableKnife4j-Annotation.
<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>- Starten Sie alle Dienste neu und greifen Sie auf den API-Dokumentpfad des Gateways zu, um Folgendes anzuzeigen: http: // localhost: 9201 / swagger-ui.html
um zusammenzufassen
Wenn man die Verwendung von Microservices zwischen Messer4j und nativem Swagger vergleicht, zeigt sich erneut, dass Messer4j eine verbesserte UI-Implementierung von Springfox-Swagger ist, die vollständig der Verwendung von Springfox-Swagger folgt.
Referenz
Offizielles Dokument: https://doc.xiaominfo.com/guide/ui-front-gateway.html
Projektquelladresse
https://github.com/macrozheng/springcloud-learning/tree/master/micro-knife4j