LinuxCommandLibrary

swagger-codegen

Generate client/server code from Swagger/OpenAPI definitions

TLDR

Generate documentation and code from an OpenAPI/swagger file

$ swagger-codegen generate [[-i|--input-spec]] [swagger_file] [[-l|--lang]] [language]
copy

Generate Java code using the library retrofit2 and the option useRxJava2
$ swagger-codegen generate [[-i|--input-spec]] [http://petstore.swagger.io/v2/swagger.json] [[-l|--lang]] [java] --library [retrofit2] -D[useRxJava2]=[true]
copy

List available languages
$ swagger-codegen langs
copy

Display help for a specific command
$ swagger-codegen [generate|config-help|meta|langs|version] --help
copy

SYNOPSIS

swagger-codegen generate -i {inputSpec} -l {language} -o {outputDir} [options]

PARAMETERS

-i, --input-spec {inputSpec}
    The input Swagger/OpenAPI definition file (YAML or JSON). This is mandatory.

-l, --lang {language}
    The target language for code generation. Supported languages include Java, Python, PHP, Javascript, C#, etc. This is mandatory.

-o, --output {outputDir}
    The output directory where the generated code will be placed. This is mandatory.

-c, --config {configurationFile}
    Path to the configuration file. Configuration file can be YAML or JSON. When specified, the values in config file override default ones.

-a, --auth {authorization}
    Add authorization headers when fetching the OpenAPI definition.

-t, --template-dir {templateDir}
    Template directory containing custom templates.

-D {property=value}
    Pass system properties to the template (e.g., -DprojectName=MyProject).

--api-package {apiPackage}
    Package for generated API classes.

--model-package {modelPackage}
    Package for generated model classes.

--group-id {groupId}
    Group ID for generated project.

--artifact-id {artifactId}
    Artifact ID for generated project.

--artifact-version {artifactVersion}
    Artifact version for generated project.

--invoker-package {invokerPackage}
    The package to use for the invoker classes (e.g., com.mycompany.invoker).

--verbose
    Verbose mode (provides more output during generation).

--dry-run
    Don't write anything to file system, just output console.

--validate-spec
    Validate the input specification (using the OpenAPI specification).

--skip-validate-spec
    Skips the validation of the input specification.

--remove-operation-id-prefix
    Remove prefix of operationId, e.g. configPet -> pet.

-h, --help
    Display help information.

DESCRIPTION

swagger-codegen is a command-line tool that automates the generation of server stubs, client SDKs, and documentation from a Swagger (OpenAPI) specification. It dramatically simplifies the process of integrating APIs into various platforms and languages. By providing an API definition in the form of a YAML or JSON file adhering to the OpenAPI specification, swagger-codegen can generate code for a wide range of programming languages (Java, Python, PHP, Javascript, etc.) and frameworks. This tool allows developers to reduce the amount of boilerplate code that would be necessary when building a new API or integrating with an existing one. It handles much of the tedious grunt work, ensuring consistency and reducing the likelihood of errors. The output can be tailored through various configuration options to fit project-specific needs.
The codegen uses templates and command-line options to customize the generated code.

CAVEATS

The generated code quality and features may vary significantly depending on the chosen language and template. Thorough testing is always recommended. Ensure that the Swagger/OpenAPI definition is valid and complete to achieve the best results. Generated code often requires customization to fully meet the needs of the target environment.

ENVIRONMENT VARIABLES

swagger-codegen uses environment variables to configure specific behaviours. The supported variables are HTTP_PROXY (to configure the proxy) and DEBUG (to enable debug output)

HISTORY

swagger-codegen initially emerged as a tool to automate the generation of server stubs and client SDKs from Swagger specifications, now known as OpenAPI specifications. Over time, it has evolved significantly, incorporating support for a wider range of languages and frameworks. The tool was initially developed as an open-source project. It gained popularity for its ability to streamline API development workflows by reducing boilerplate code and promoting consistency. Further development is continued as OpenAPI Generator, an Apache 2.0 licensed fork.

SEE ALSO

curl(1), jq(1), openapi(1)

Copied to clipboard