Микросервисы агрегируют документы Swagger, эта волна операций действительно ароматна!

Адрес фактического центра электронной коммерции SpringBoot (35k+star):GitHub.com/macro-positive/…

Резюме

помни мойmall-swarmВ проекте микросервиса отсутствует агрегация документов API, и для доступа к документу API каждого сервиса требуется доступ к отдельномуswagger-ui.htmlстраница, поскольку мы используем микросервисы, должна быть единая запись документа API, недавно обнаруженнаяknife4jПри такой поддержке в этой статье будет подробно описана его реализация, надеюсь всем поможет!

Предварительное знание

Мы будем использовать Nacos в качестве реестра и Gateway в качестве шлюза, используяknife4jЧтобы создать документацию по API, друзья, не знакомые с этими технологиями, могут прочитать следующие статьи.

Spring Cloud Gateway: новое поколение сервисов шлюза API
Spring Cloud Alibaba: Nacos используется как центр регистрации и настройки
Поменял новый скин на Swagger, и мгновенно стал выше!

Архитектура приложения

Наше идеальное решение должно быть таким, шлюз действует как единая запись для документов API, шлюз агрегирует документы всех микросервисов и обращается к документам API других сервисов, переключаясь на шлюзе.

Сопутствующее сервисное подразделение:

micro-knife4j-gateway: служба шлюза, используемая в качестве записи доступа к документам API микросервиса, объединяет все документы API и нуждается в представлении пакета интерфейсного пользовательского интерфейса документа;
micro-knife4j-user: служба пользователя, общая служба API, нет необходимости вводить пакет пользовательского интерфейса для документов;
micro-knife4j-order: служба заказа, общая служба API, нет необходимости вводить пакет пользовательского интерфейса документа.

Выполнение

Конкретная реализация документа API агрегации Spring Cloud Gateway + knife4j подробно описана ниже, а сервис пользователя, сервис заказа и сервис шлюза построены по очереди.

micro-knife4j-user

Давайте сначала создадим пользовательский сервис, обычный сервис API, который очень прост и может быть интегрирован с knife4j всего за три шага.

существуетpom.xmlДобавьте связанные зависимости, зависимость веб-функции SpringBoot, зависимость микросервиса knife4j (интерфейсный пакет пользовательского интерфейса, который не содержит документации по 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>

существуетapplication.ymlЭто добавляет соответствующую конфигурацию и настраивает центр регистрации 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: "*"

Добавить конфигурацию, связанную с Swagger, очень общую конфигурацию, добавить@EnableKnife4jАннотация позволяет вносить улучшения в 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-knife4j-order

Далее мы создадим сервис заказов, общий сервис API, просто обратитесь к построению пользовательского сервиса выше.

micro-knife4j-gateway

Наконец, мы создаем службу шлюза как единую запись для документов API микрослужб, которая объединяет документы API всех микрослужб.

существуетpom.xmlДобавьте связанные зависимости, зависимости, связанные со шлюзом, и Knife4j Starter (интерфейсный пакет пользовательского интерфейса, содержащий документацию по 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>

существуетapplication.ymlЭто добавляет соответствующую конфигурацию, настраивает маршрутизацию центра регистрации Nacos, обслуживание пользователей и службу заказов;

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 #使用小写服务名，默认是大写

Добавьте конфигурацию ресурсов Swagger на шлюз для агрегирования Swagger в других микросервисах.api-docsпуть доступа;

/**
 * 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;
    }
}

Что такое чванствоapi-docsпуть доступа? Этот путь будет возвращать данные в формате JSON, откуда берутся все данные для Swagger для отображения страницы документации API.Например, наша служба пользователя вернет следующую информацию, адрес доступа:http://localhost:9201/user-service/v2/api-docs

Далее нам нужно настроить узлы каждой конфигурации Swagger, Короче говоря, это настроить каждый интерфейс для получения данных внутри 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)));
    }
}

Напримерswagger-resourcesЭтот интерфейс можно использовать для получения всех микросервисов.api-docsПуть доступа, получить информацию следующим образом, адрес доступа:http://localhost:9201/swagger-resources

Демо

Далее давайте продемонстрируем функцию агрегации документов API микросервиса Вам нужно только посетить страницу документа API шлюза, и вы можете самостоятельно переключиться на документ API связанного сервиса.

Перед этим запустите наш реестр Nacos, а затем запуститеmicro-knife4j-user,micro-knife4j-orderиmicro-knife4j-gatewayСлужить;

Чтобы получить доступ к документации API из шлюза, посетите адрес:http://localhost:9201/doc.html

Мы можем переключиться на документ API соответствующей услуги через компонент коммутатора в верхнем левом углу;

Глядя на документацию API, мы можем обнаружить, что все интерфейсы были добавлены с соответствующими префиксами доступа и могут быть доступны в обычном режиме.

Вернуться к пользовательскому интерфейсу Swagger

Если вы не хотите использовать интерфейс knife4j и хотите использовать оригинальный интерфейс Swagger, он также может поддерживаться.Метод переключения очень прост.Давайте поговорим об этом.

Сначала нам нужноpom.xmlСоответствующие зависимости knife4j удалены из , в основном следующие две зависимости;

<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>

существуетpom.xmlДобавьте зависимости, связанные со Swagger, и удалите исходные.@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>

Перезапустите все службы и перейдите по пути к документу API шлюза, чтобы просмотреть:http://localhost:9201/swagger-ui.html

Суммировать

Сравнивая использование микросервиса knife4j и нативного Swagger, это еще раз доказывает, что knife4j — это расширенная реализация пользовательского интерфейса springfox-swagger, которая полностью соответствует использованию в springfox-swagger.

использованная литература

Официальная документация:doc.xiaomingfo.com/expensive/UI-введите…

Адрес исходного кода проекта

GitHub.com/macro-positive/…

публика

проект торгового центраПолный набор учебных пособий сериализуется,Обратите внимание на публичный аккаунтПолучите это прямо сейчас.