search

swagger-api / swagger-codegen

swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.
http://swagger.io
Apache License 2.0
16.89k stars 6.03k forks source link

Document config options for language #7795

Open marcelstoer opened 6 years ago

marcelstoer commented 6 years ago

I recently searched high and low for a documentation of all the config options and didn't find anything. I believe this is a general problem but in my case I was interested specifically in the options for Java as I was generating with the swagger-codegen-maven-plugin. It's README says:

configOptions - a map of language-specific parameters (see below)

Yet, nowhere "below" are the options documented.

I thought about opening a PR to add the Java documentation (as follows) to the README. Maybe some guidance from @wing328 would be needed.

wing328 commented 6 years ago

@marcelstoer are you looking for the following commands to show the general options and language-specific option?

General: java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar help generate

Language-specific: java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar config-help -l java

marcelstoer commented 6 years ago

No, I'm familiar with the commands (they produced the above list) but I expected the documentation to include the language-specific options.

bxnkole commented 6 years ago

This could also be useful https://generator.swagger.io/api/gen/clients/java

harshitbansal1992 commented 5 years ago

Is there an option to use specific annotations from the library for eg: For each model I wish to use Jackson annotation @JsonInclude(Include.NON_NULL) Also, if I want to use other than the specified libraries ... is that possible ?

aratakokubun commented 5 years ago

@harshitbansal1992 Have you already resolved the issue? I really want that option to depend libraries as less as possible!

verokarhu commented 5 years ago

Currently this issue seems to be the best documentation on the different options for Java. Having to download a separate jar just to list the options is not an option.

foal commented 5 years ago

Just put it into README :)

anandsunderraman commented 5 years ago

Actually there exists comprehensive documentation in another repo: https://github.com/OpenAPITools/openapi-generator/tree/master/docs/generators

tyler2cr commented 4 years ago

The configHelp parameter (right below configOptions) says that it "dumps the configuration help for the specified library (generates no sources)". I've incorporated this as part of my build lifecycle so I don't need to run the jar command manually. The list of configOptions that @marcelstoer posted gets printed as part of the build:

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.3.1</version>
    <executions>
        <execution>
            <id>generate "configOptions" for java</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>swagger.yaml</inputSpec>
                <configHelp>true</configHelp>
                <language>java</language>
            </configuration>
        </execution>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>swagger.yaml</inputSpec>

                <language>java</language>

                <configOptions>
                    <dateLibrary>java8</dateLibrary>
                </configOptions>

                <library>resttemplate</library>
            </configuration>
        </execution>
    </executions>
</plugin>
.
.
.
[INFO] --- swagger-codegen-maven-plugin:2.3.1:generate (generate "configOptions" for java) @ swagger.codegen.proof.of.concept ---
[INFO] reading from swagger.yaml
        sortParamsByRequiredFlag
            Sort method arguments to place required parameters before optional parameters. (Default: true)

        ensureUniqueParams
            Whether to ensure parameter names are unique in an operation (rename parameters that are not). (Default: true)

        allowUnicodeIdentifiers
            boolean, toggles whether unicode identifiers are allowed in names or not, default is false (Default: false)

        modelPackage
            package for generated models

        apiPackage
            package for generated api classes

        invokerPackage
            root package for generated code

        groupId
            groupId in generated pom.xml

        artifactId
            artifactId in generated pom.xml

        artifactVersion
            artifact version in generated pom.xml

        artifactUrl
            artifact URL in generated pom.xml

        artifactDescription
            artifact description in generated pom.xml

        scmConnection
            SCM connection in generated pom.xml

        scmDeveloperConnection
            SCM developer connection in generated pom.xml

        scmUrl
            SCM URL in generated pom.xml

        developerName
            developer name in generated pom.xml

        developerEmail
            developer email in generated pom.xml

        developerOrganization
            developer organization in generated pom.xml

        developerOrganizationUrl
            developer organization URL in generated pom.xml

        licenseName
            The name of the license

        licenseUrl
            The URL of the license

        sourceFolder
            source folder for generated code

        localVariablePrefix
            prefix for generated code members and local variables

        serializableModel
            boolean - toggle "implements Serializable" for generated models (Default: false)

        bigDecimalAsString
            Treat BigDecimal values as Strings to avoid precision loss. (Default: false)

        fullJavaUtil
            whether to use fully qualified name for classes under java.util. This option only works for Java API client (Default: false)

        hideGenerationTimestamp
            hides the timestamp when files were generated

        withXml
            whether to include support for application/xml content type and include XML annotations in the model (works with libraries that provide support for JSON and XML) (Default: false)

        dateLibrary
            Option. Date library to use
                joda - Joda (for legacy app only)
                legacy - Legacy java.util.Date (if you really have a good reason not to use threetenbp
                java8-localdatetime - Java 8 using LocalDateTime (for legacy app only)
                java8 - Java 8 native JSR310 (preferred for jdk 1.8+) - note: this also sets "java8" to true
                threetenbp - Backport of JSR310 (preferred for jdk < 1.8)

        java8
            Option. Use Java8 classes instead of third party equivalents
                true - Use Java 8 classes such as Base64
                false - Various third party libraries as needed

        useRxJava
            Whether to use the RxJava adapter with the retrofit2 library. (Default: false)

        useRxJava2
            Whether to use the RxJava2 adapter with the retrofit2 library. (Default: false)

        parcelableModel
            Whether to generate models for Android that implement Parcelable with the okhttp-gson library. (Default: false)

        usePlayWS
            Use Play! Async HTTP client (Play WS API) (Default: false)

        playVersion
            Version of Play! Framework (possible values "play24", "play25")

        supportJava6
            Whether to support Java6 with the Jersey1 library. (Default: false)

        useBeanValidation
            Use BeanValidation API annotations (Default: false)

        performBeanValidation
            Perform BeanValidation (Default: false)

        useGzipFeature
            Send gzip-encoded requests (Default: false)

        useRuntimeException
            Use RuntimeException instead of Exception (Default: false)

        library
            library template (sub-template) to use (Default: okhttp-gson)
                jersey1 - HTTP client: Jersey client 1.19.4. JSON processing: Jackson 2.8.9. Enable Java6 support using '-DsupportJava6=true'. Enable gzip request encoding using '-DuseGzipFeature=true'.
                feign - HTTP client: OpenFeign 9.4.0. JSON processing: Jackson 2.8.9
                jersey2 - HTTP client: Jersey client 2.25.1. JSON processing: Jackson 2.8.9
                okhttp-gson - HTTP client: OkHttp 2.7.5. JSON processing: Gson 2.8.1. Enable Parcelable models on Android using '-DparcelableModel=true'. Enable gzip request encoding using '-DuseGzipFeature=true'.
                retrofit - HTTP client: OkHttp 2.7.5. JSON processing: Gson 2.3.1 (Retrofit 1.9.0). IMPORTANT NOTE: retrofit1.x is no longer actively maintained so please upgrade to 'retrofit2' instead.
                retrofit2 - HTTP client: OkHttp 3.8.0. JSON processing: Gson 2.6.1 (Retrofit 2.3.0). Enable the RxJava adapter using '-DuseRxJava[2]=true'. (RxJava 1.x or 2.x)
                resttemplate - HTTP client: Spring RestTemplate 4.3.9-RELEASE. JSON processing: Jackson 2.8.9
                resteasy - HTTP client: Resteasy client 3.1.3.Final. JSON processing: Jackson 2.8.9
                vertx - HTTP client: VertX client 3.2.4. JSON processing: Jackson 2.8.9
                google-api-client - HTTP client: Google API client 1.23.0. JSON processing: Jackson 2.8.9

[INFO] 
[INFO] --- swagger-codegen-maven-plugin:2.3.1:generate (default) @ swagger.codegen.proof.of.concept ---
[INFO] reading from swagger.yaml
.
.
.
flocheke7 commented 4 years ago

interfaceOnly option no longer exists ???

liangzuobin commented 4 years ago

And those System Properties.

mfaisalhyder commented 6 months ago

Is there a way to disable @Schema from generated photos?

OpenApiTools has that but swagger-codegen seems to be missing it from both java and spring language.