How to skip generation of support and metadata files with openAPI Generator and Maven?

Question

I'm converting a swagger file into an open API v3 one using the openapi-yaml generator with Maven.

What I would like to do is to put the new file directly into some directory.

However some additional files are generated which I don't need e.g. README.md, .openapi-generator/VERSION, .openapi-generator-ignore

Is it possible to disable this behaviour and generate only the .yaml file?

Bald

Answer 1

You can specify what you are going to generate or what to exclude from generation using the command parameter --global-property

Take a look at the docs: https://openapi-generator.tech/docs/customization/#selective-generation

It says:

You may not want to generate all models in your project. Likewise, you may want just one or two apis to be written. If that's the case, you can use system properties or global properties to control the output.

The default is generate everything supported by the specific library. Once you enable a feature, it will restrict the contents generated:

# generate only models
--global-property models
# generate only apis
--global-property apis
# generate only supporting files
--global-property supportingFiles
# generate models and supporting files
--global-property models,supportingFiles

To control the specific files being generated, you can pass a CSV list of what you want:

# generate the User and Pet models only
--global-property models="User:Pet"
# generate the User model and the supportingFile `StringUtil.java`:
--global-property models=User,supportingFiles=StringUtil.java

To control generation of docs and tests for api and models, pass false to the option. For api, these options are --global-property apiTests=false,apiDocs=false. For models, --global-property modelTests=false,modelDocs=false. These options default to true and don't limit the generation of the feature options listed above (like --global-property api):

# generate only models (with tests and documentation)
--global-property models
# generate only models (with tests but no documentation)
--global-property models,modelDocs=false
# generate only User and Pet models (no tests and no documentation)
--global-property models="User:Pet",modelTests=false
# generate only apis (without tests)
--global-property apis,apiTests=false
# generate only apis (modelTests option is ignored)
--global-property apis,modelTests=false

When using selective generation, only the templates needed for the specific generation will be used.

To skip models defined as the form parameters in "requestBody", please use skipFormModel (default to true) (this option is introduced at v3.2.2 and true by default starting from v5.x).

--global-property skipFormModel=true

This option will be helpful to skip model generation due to the form parameter, which is defined differently in OAS3 as there's no form parameter in OAS3

Wheal

This was really useful--I had specified a certain api with apis and then couldn't figure out why i was getting a bunch of compilation errors when models/supporting files (specifically runtime.ts in my case) weren't generated. – Playback

Answer 2

It still doesn't look possible directly through the openApiGenerate config. As other suggest it can be done through a script though. As there's no example, here's what I put together by extending the gradle task

openApiGenerate {
    generatorName = "java"
    inputSpec = (String) "$buildDir/openapi.json"
    outputDir =  (String) "$rootDir/generated-client"
    apiPackage = "com.example.client.api"
    modelPackage = "com.example.client.model"
    invokerPackage = "com.example.client.invoker"
}

tasks.openApiGenerate {
    doLast {
        delete (
                "$rootDir/generated-client/.openapi-generator",
                "$rootDir/generated-client/api",
                "$rootDir/generated-client/gradle",
                "$rootDir/generated-client/docs"
        )
    }
}

Sodomite

Answer 3

Yes this is possible using a .openapi-generator-ignore file as documented at:

https://github.com/OpenAPITools/openapi-generator/blob/master/docs/customization.md#ignore-file-format

For example, to skip git_push.sh, one can create a file named .openapi-generator-ignore in the root of the output directory with the contents:

# Prevent generator from creating these files:
git_push.sh

Some good documentation can also be found at:

https://openapi-generator.tech/docs/faq-extending/#how-do-i-skip-files-during-code-generation

Feminine

This will only stop the generator from overwriting those files, they will however still get generated if they're not present. – Darbydarce

@GregorA.Lamche It is also stated on the FAQ : If you need this functionality on initial generation, you can provide the option --ignore-file-override (CLI) or ignoreFileOverride (Maven and Gradle plugins) with a value targeting any existing file. It worked for me (with this caveat). – Waterfall

Answer 4

I would suggest you to keep these files. README.md help others to understand the code. VERSION shows which version of openapi-generator you're using. .openapi-generator-ignore works similar to .gitignore to skip certain files from being generated

Putting README.md and .openapi-generator/VERSION in .openapi-generator-ignore will skip these files from being generated.

To "ignore" .openapi-generator folder, you can post-process the output with a script and delete the files/folders that you don't want.

Bitternut

Hi William, thanks for the suggestion. Regretfully it didn't work the way I want to. I'm unable to ignore the .openapi-generator folder. My use case is quite simple - I'm just generating OAS 3 document (which is always up to date since based on the code) and all other files doesn't make much sense. – Bald

Op didnt ask for your oppinion on what he wants to do he ask if it is possible. -1 – Zooplasty

This doesn't work. I am using version 5.0.0 of the generator and even though I put .openapi-generator/** in the ignore file, it still generates every file inside .openapi-generator/ – Heroine

To "ignore" .openapi-generator folder, you can post-process the output with a script and delete the files/folders that you don't want. – Bitternut

Can you update your answer that the only solution is post processing? – Anodic

Answer 5

this is the solution that was working for me i am using gradle

buildscript {
    repositories {
        maven {
            url = uri("https://plugins.gradle.org/m2/")
        }
    }
    dependencies {
        classpath("org.openapitools:openapi-generator-gradle-plugin:7.1.0")
    }
}

import org.openapitools.generator.gradle.plugin.tasks.GenerateTask


tasks.register("generatePartsApi", GenerateTask) {
    var apiName = "parts"
    generatorName.set("spring")
    library.set("spring-http-interface")
    inputSpec.set("/parts/build/parts.yaml")
    outputDir.set("$buildDir/openapi/${apiName}")
    apiPackage.set("com.company.api.${apiName}.api")
    invokerPackage.set("com.company.api.${apiName}.invoker")
    modelPackage.set("com.company.api.${apiName}.model")
    configOptions.set([
            configPackage        : "com.company.api.${apiName}.config",
            openApiNullable      : "false",
            documentationProvider: 'none',
            annotationLibrary    : "none",
            useJakartaEe         : 'true',
    ])
    ignoreFileOverride.set("$rootDir/gradle/.openapi-generator-ignore")
    sourceSets.main.java.srcDirs += "$buildDir/openapi/${apiName}/src/main/java"


}


sourceSets.main.java.srcDirs += "$buildDir/openapi/src/main/java"
compileJava.dependsOn 'generatePartsApi'

this is the content of the .openapi-generator-ignore file

# OpenAPI Generator Ignore
# Generated by openapi-generator https://github.com/openapitools/openapi-generator


# Exclude Configurator classes
**/HttpInterfacesAbstractConfigurator.java
pom.xml

Marylinmarylinda