Настройка плагина OpenAPI Generator в формате TOML для Gradle 8.2.0

Содержание

• Правильная конфигурация TOML
• Настройка build.gradle
• Полный рабочий пример
• Распространенные проблемы и устранение неполадок
• Дополнительные параметры конфигурации

Правильная конфигурация TOML

Ваша структура файла TOML выглядит правильно, но есть несколько деталей, которые необходимо учесть для корректной работы. Создайте файл gradle/libs.versions.toml со следующей конфигурацией:

[versions]
openapi-tools = "7.2.0"

[plugins]
openapi-generator = { 
    id = "org.openapi.generator", 
    version.ref = "openapi-tools" 
}

Ключевые моменты для проверки:

• Файл должен называться точно libs.versions.toml и находиться в вашей директории gradle/
• Используйте version.ref для ссылки на версию из раздела [versions]
• ID плагина должен совпадать точно: “org.openapi.generator”

Согласно документации Gradle по версиям каталогов, это стандартный синтаксис для объявления плагинов в формате TOML.

Настройка build.gradle

В вашем файле build.gradle или build.gradle.kts используйте псевдоним плагина, как вы пытались сделать:

plugins {
    alias(libs.plugins.openapi.generator)
}

Однако вам также необходимо применить плагин в вашем build-скрипте. Вот полная настройка:

plugins {
    alias(libs.plugins.openapi.generator)
}

// Дополнительная конфигурация для OpenAPI Generator
openApiGenerate {
    generatorName = "spring" // или ваш предпочитаемый генератор
    inputSpec = "$projectDir/src/main/resources/api.yaml"
    outputDir = "$buildDir/generated"
    apiPackage = "com.example.api"
    modelPackage = "com.example.model"
    configOptions = [
        interfaceOnly: "true",
        openApiNullable: "false"
    ]
}

Полный рабочий пример

Вот полный рабочий пример настройки:

1. Структура проекта:

my-project/
├── gradle/
│   └── libs.versions.toml
├── build.gradle
├── settings.gradle
└── src/
    └── main/
        └── resources/
            └── api.yaml

2. gradle/libs.versions.toml:

[versions]
openapi-tools = "7.2.0"

[plugins]
openapi-generator = { 
    id = "org.openapi.generator", 
    version.ref = "openapi-tools" 
}

3. build.gradle:

plugins {
    alias(libs.plugins.openapi.generator)
}

openApiGenerate {
    generatorName = "spring"
    inputSpec = "$projectDir/src/main/resources/api.yaml"
    outputDir = "$buildDir/generated"
    apiPackage = "com.example.api"
    modelPackage = "com.example.model"
    configOptions = [
        interfaceOnly: "true",
        openApiNullable: "false",
        skipDefaultInterface: "true"
    ]
    globalProperties = [
        apis: "",
        models: ""
    ]
}

// Добавление сгенерированных источников в исходный набор
sourceSets.main.java.srcDir "$buildDir/generated/src/main/java"

Распространенные проблемы и устранение неполадок

1. Gradle не может найти плагин:

Если вы столкнулись с ошибкой “Could not find plugin ‘org.openapi.generator’”, проверьте:

• Ваш файл libs.versions.toml находится в правильном месте (директория gradle/)
• ID плагина написан точно: “org.openapi.generator”
• Gradle кэшировал каталог версий - попробуйте выполнить ./gradlew clean build --refresh-dependencies

2. Проблемы с разрешением версий:

Если Gradle не может разрешить версию, убедитесь:

• Номер версии в разделе [versions] соответствует доступным версиям
• Вы используете поддерживаемую версию плагина с Gradle 8.2.0

3. Интеграция с IDE:

Согласно исследованиям из softAai Blogs, для Gradle 8+ каталоги версий включены по умолчанию, но убедитесь:

• В вашей IDE установлен плагин TOML (Android Studio включает его в комплект)
• Вы обновили проекты Gradle в своей IDE после внесения изменений

Дополнительные параметры конфигурации

Для более сложных настроек вы можете расширить свою конфигурацию:

1. Несколько генераторов:

[versions]
openapi-tools = "7.2.0"

[plugins]
openapi-generator = { 
    id = "org.openapi.generator", 
    version.ref = "openapi-tools" 
}

[libraries]
openapi-generator-cli = { 
    group = "org.openapitools", 
    name = "openapi-generator-cli", 
    version.ref = "openapi-tools" 
}

2. Пользовательская конфигурация генератора:

openApiGenerate {
    generatorName = "typescript-fetch"
    inputSpec = "$projectDir/openapi.yaml"
    outputDir = "$projectDir/src/gen/typescript/api"
    apiPackage = "api"
    modelPackage = "model"
    configOptions = [
        npmName: "my-api-client",
        npmVersion: "1.0.0",
        npmRepository: "https://registry.npmjs.org/",
        useSingleRequestParameter: "true"
    ]
}

3. Конфигурация задачи:

tasks.named("openApiGenerate") {
    dependsOn("validateOpenApi")
}

task validateOpenApi(type: io.github.swagger2markup.markup.DocumentTask) {
    inputSpec = "$projectDir/src/main/resources/api.yaml"
    outputDir = projectDir.path + "/docs/overview"
}

Не забудьте выполнить ./gradlew openApiGenerate после настройки для проверки вашей конфигурации. Эта настройка должна работать безупречно с Gradle 8.2.0 и предоставить вам современное централизованное управление зависимостями, которое вы ищете.

Источники

1. Документация Gradle по каталогам версий
2. Maven Repository - openapi-generator-gradle-plugin
3. Gradle Goodness: Определение версий плагинов с использованием каталога версий
4. Каталог версий Gradle в Android: Полное руководство
5. Stack Overflow - Конфигурация Gradle для OpenAPI Generator

Заключение

• Правильная конфигурация TOML требует правильного синтаксиса с version.ref, ссылающимся на версию из раздела [versions]
• Убедитесь, что ваш файл libs.versions.toml находится в директории gradle/ с точным именем файла
• Используйте alias(libs.plugins.openapi.generator) в вашем файле build.gradle для ссылки на плагин
• Проверьте, что Gradle может разрешить зависимости, выполнив с флагом --refresh-dependencies при необходимости
• Конфигурация плагина поддерживает все стандартные параметры OpenAPI Generator через DSL

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