Вопрос или проблема
Учитывая следующий фрагмент OpenAPI YAML …
openapi: 3.0.3
info:
title: API клиента
description: |
Через этот API платформа может взаимодействовать с приложением, которое управляет контрактами клиентов
version: 0.5.0
license:
name: Лицензия компании
url: https://www.company.com/license
contact:
email: [email protected]
name: Джон Доу
url: https://www.company.com/contact
servers:
- url: https://application-test.company.com
description: Тестовая среда
- url: https://application-uat.company.com
description: Среда приемочного тестирования
- url: https://application.company.com
description: Производственная среда
tags:
- name: ввод
description: Действия, связанные с отправкой и получением контрактов клиентов
- name: вывод
description: Действия, связанные с получением контрактов клиентов
paths:
...
… Я использую OpenAPI Generator Maven Plugin для вызова генератора spring
<plugin>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>7.8.0</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>
${project.basedir}/src/main/resources/app-api.yaml
</inputSpec>
<generatorName>spring</generatorName>
<apiPackage>com.company.application.api</apiPackage>
<modelPackage>com.company.application.api.model</modelPackage>
<supportingFilesToGenerate>
ApiUtil.java,SpringDocConfiguration.java
</supportingFilesToGenerate>
<configOptions>
<skipIfSpecIsUnchanged>true</skipIfSpecIsUnchanged>
<useSpringBoot3>true</useSpringBoot3>
<generateBuilders>true</generateBuilders>
<annotationLibrary>swagger2</annotationLibrary>
</configOptions>
</configuration>
</execution>
</executions>
</plugin>
… для генерации соответствующей SpringDocConfiguration:
@Configuration
public class SpringDocConfiguration {
@Bean(name = "org.openapitools.configuration.SpringDocConfiguration.apiInfo")
OpenAPI apiInfo() {
return new OpenAPI()
.info(
new Info()
.title("API клиента")
.description("Через этот API платформа может взаимодействовать с приложением, которое управляет контрактами клиентов")
.contact(
new Contact()
.name("Джон Доу")
.url("https://www.company.com/contact")
.email("[email protected]")
)
.license(
new License()
.name("Лицензия компании")
.url("https://www.company.com/license")
)
.version("0.5.0")
)
.servers(...) // отсутствует
.tags(...) // отсутствует
;
}
}
Обратите внимание, что вся информация info была сгенерирована корректно, но servers и tags отсутствуют.
Я нашел разрешенный PR на Github, который предполагает, что это (по крайней мере servers) было реализовано, но каким-то образом не применяется.
Я также не смог найти подходящий параметр конфигурации в документации генератора Spring, чтобы включить его.
Поэтому, как я могу сгенерировать информацию о server и tag с помощью OpenAPI Generator Maven Plugin в SpringDocConfiguration или любой другой файл? Это вообще возможно? Это вопрос конфигурации или отсутствия зависимостей?
В коде, как я вижу, servers и tags находятся в разделе info, но в yaml servers и tags находятся на одном уровне. Попробуйте добавить пробелы перед servers и tags, чтобы поместить их в блок info:
info:
title:
...
servers:
tags:
Ответ или решение
Чтобы сгенерировать информацию о серверах и тегах из YAML-файла OpenAPI в класс SpringDocConfiguration, вы можете следовать следующему подходу.
Шаги для решения проблемы
-
Структура YAML: Убедитесь, что структура вашего YAML-документа соответствует требованиям спецификации OpenAPI. Сервера и теги должны находиться на одном уровне с
info, а не внутри него. Пример правильной структуры:openapi: 3.0.3 info: title: Customer API description: | Through this API, the platform can communicate with the application which manages customer contracts version: 0.5.0 license: name: Company license url: https://www.company.com/license contact: email: [email protected] name: John Doe url: https://www.company.com/contact servers: - url: https://application-test.company.com description: Test Environment - url: https://application-uat.company.com description: User Acceptance Environment - url: https://application.company.com description: Production Environment tags: - name: input description: Actions related to sending and retrieving of customer contracts - name: output description: Actions related to getting customer contracts paths: ... -
Настройки OpenAPI Generator: Убедитесь, что вы используете правильную конфигурацию для генерации кода. Ваш текущий конфигурационный фрагмент выглядит корректно, но важно следить за версиями. Особенно проверьте актуальность используемой версии
openapi-generator-maven-plugin. -
Генерация
SpringDocConfiguration: После внесения изменений в YAML-файл, используйте OpenAPI Generator для пересоздания вашего проекта. При этом обеспечьте, чтобы в конфигурации сгенерированного классаSpringDocConfigurationдобавлялись параметрыserversиtags. -
Внедрение
serversиtagsвSpringDocConfiguration: Вам нужно будет добавить соответствующие методы генерации дляserversиtagsв классSpringDocConfiguration. Пример кода ниже показывает, как это может выглядеть:@Configuration public class SpringDocConfiguration { @Bean(name = "org.openapitools.configuration.SpringDocConfiguration.apiInfo") OpenAPI apiInfo() { return new OpenAPI() .info( new Info() .title("Customer API") .description("Through this API, the platform can communicate with the application which manages customer contracts") .contact( new Contact() .name("John Doe") .url("https://www.company.com/contact") .email("[email protected]") ) .license( new License() .name("Company license") .url("https://www.company.com/license") ) .version("0.5.0") ) .servers(Arrays.asList( new Server().url("https://application-test.company.com").description("Test Environment"), new Server().url("https://application-uat.company.com").description("User Acceptance Environment"), new Server().url("https://application.company.com").description("Production Environment") )) .tags(Arrays.asList( new Tag().name("input").description("Actions related to sending and retrieving of customer contracts"), new Tag().name("output").description("Actions related to getting customer contracts") )); } }
Заключение
Убедитесь, что структура YAML корректна, и обновите ваш код для создания серверов и тегов, как указано выше. Это обеспечит правильную генерацию необходимой информации. Если после этих изменений возникнут проблемы, возможно, потребуется проверить версии плагина и зависимости, а также документацию OpenAPI Generator для получения обновленной информации о лучших практиках.