Добавление заглушек сервера Swagger в существующее приложение Spring

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

Это описание предназначено для создания и использования заглушки сервера spring-mvc из спецификации OpenApi 3.0.0 с использованием плагина openapi-generator-maven.

1. Не используйте swagger-codegen, вместо этого используйте генератор openapi: https://github.com/OpenAPITools/openapi-generator (обоснование форка здесь: https://github.com/OpenAPITools/openapi-generator/blob/master/docs/qna.md)

2. Создайте отдельный проект/модуль для сервера и настройте плагин maven.

<build>
    <plugins>
        <plugin>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator-maven-plugin</artifactId>
            <version>3.3.4</version>
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <skipIfSpecIsUnchanged>true</skipIfSpecIsUnchanged>
                        <inputSpec>${engine-openapi-spec.location}</inputSpec>
                        <output>${project.build.directory}/generated-sources/openapi</output>
                        <generatorName>spring</generatorName>
                        <library>spring-mvc</library>
                        <apiPackage>eu.dorsum.swift.engine.service.api</apiPackage>
                        <modelPackage>eu.dorsum.swift.engine.service.model</modelPackage>
                        <generateApis>true</generateApis>
                        <generateApiDocumentation>false</generateApiDocumentation>
                        <generateApiTests>false</generateApiTests>
                        <generateModels>true</generateModels>
                        <generateModelDocumentation>false</generateModelDocumentation>
                        <generateModelTests>false</generateModelTests>
                        <generateSupportingFiles>true</generateSupportingFiles>
                        <configOptions>
                            <sourceFolder>src/main/java</sourceFolder>
                            <java8>true</java8>
                            <dateLibrary>java8</dateLibrary>
                            <useTags>true</useTags>
                            <configPackage>eu.dorsum.swift.engine.appconfig</configPackage>
                            <interfaceOnly>false</interfaceOnly>
                            <delegatePattern>true</delegatePattern>
                        </configOptions>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Есть две части конфигурации, которые довольно сложно понять.

2.a: Установите configOptions/configPackage для пакета, в котором находится корневая конфигурация вашего приложения. Эта опция добавит ваш пакет конфигурации в качестве дополнительного basePackage для сканирования компонентов в OpenAPIUiConfiguration.java: @ComponentScan(basePackages = {"eu.dorsum.swift.engine.service.api", "eu.dorsum.swift.engine.appconfig"}). Это перевернутый подход, о котором вы могли подумать изначально, когда сгенерированная конфигурация mvc запускает ваши существующие вещи, но это единственный способ, который я нашел, не требующий изменений в сгенерированном коде.

2.b: Установите configOptions/delegatePattern в значение true. Этот мне очень нравится! Это создаст дополнительный интерфейс делегирования, который может реализовать ваш серверный контроллер. Сгенерированный ApiController делегирует все вызовы службы этому интерфейсу, так что вы можете очень элегантно подключить свою реализацию. В моей настройке у меня есть эта цепочка: MessageApi (сгенерированный интерфейс) -> MessageApiController реализует MessageApi (сгенерированный контроллер mvc) -> MessageApiDelegate (сгенерированный интерфейс) -> MessageService реализует MessageApiDelegate (моя реализация методов службы).

Имея эти две части конфигурации, нет необходимости изменять сгенерированные исходники. Если спецификация API изменяет интерфейс делегирования, вы должны реализовать эти изменения в MessageService.

Ниже приведено обновление моего исходного сообщения, в котором более подробно объясняется, как реализация службы связана с интерфейсом делегата.

Исходники, созданные openapi-gen, находятся в отдельном модуле jar, содержащем только swagger.yaml и pom.xml в качестве зарегистрированных «источников». Модуль, использующий сгенерированный код, — это война, которая имеет прямую зависимость от сгенерированного jar. Реализация службы находится в состоянии войны и реализует интерфейс MessageApiDelegate, который находится в сгенерированном источнике. Контекст Spring извлекается из сгенерированного кода, и пакеты, которые вы определяете как apiPackage и configPackage в конфигурации openapi-gen, будут добавлены как basePackages для @ComponentScan в сгенерированном OpenAPIUiConfiguration.java, поэтому реализация вашей службы должна быть помещена в или под apiPackages.

Вот упрощенная структура, чтобы собрать части вместе.

parent/
  swift-engin-service/ (generated jar module)
    swagger.yaml
    pom.xml
    target/generated-sources/openapi/src/main/java/eu/dorsum/swift/engine/
      appconfig/ (generated spring webmvc config)
        OpenAPIUiConfiguration.java
        WebApplication.java (brings up spring context by extending AbstractAnnotationConfigDispatcherServletInitializer)
      service/
        MessageApiController.java (@Controller, @RequestMapping etc.)
        MessageApiDelegate.java (implement this to get your service implementation plugged in the controller)
  swift-engine/ (war module, your code)
    pom.xml
    src/main/java/eu/dorsum/swift/engine/
      appconfig/
        EngineConfig.java (my spring config)
      service/api/ (must be the same as apiPackages property)
        MessageService.java (service implementation)

Соответствующая часть swift-engine/pom.xml

<project>
    <packaging>war</packaging>

    <dependencies>
        <dependency>
            <groupId>eu.dorsum.core.java.swift-engine</groupId>
            <artifactId>swift-engine-service</artifactId>
        </dependency>
    </dependencies>
</project>

Соответствующая часть eu.dorsum.swift.engine.service.api.MessageService

@Service
public class MessageService implements MessageApiDelegate {
    @Override
    public ResponseEntity<List<SwiftMessage>> listMessages(List<String> sorting, Integer pageStart, Integer pageSize, String filter) {
        // implementation
    }

    @Override
    public ResponseEntity<Void> updateMessage(SwiftMessage message) {
        // implementation
    }
}

Соответствующая часть eu.dorsum.swift.engine.appconfig.OpenAPIUiConfiguration (сгенерирована)

@Configuration
@ComponentScan(basePackages = {"eu.dorsum.swift.engine.service.api", "eu.dorsum.swift.engine.appconfig"})
@EnableWebMvc
public class OpenAPIUiConfiguration extends WebMvcConfigurerAdapter {
    ...
}