swagger-codegen

Generate documentation and code from an OpenAPI/swagger file

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

$ swagger-codegen generate [[-i|--input-spec]] [http://petstore.swagger.io/v2/swagger.json] [[-l|--lang]] [java] --library [retrofit2] -D[useRxJava2]=[true]

$ swagger-codegen langs

$ swagger-codegen [generate|config-help|meta|langs|version] --help

swagger-codegen command [command-options]

The primary command structure involves invoking swagger-codegen followed by a specific command and its associated options. The most frequently used command is `generate`.

Example for `generate` command:
swagger-codegen generate -i <input_spec> -l <language> -o <output_dir>

-i, --input-spec
    Specifies the path or URL to the OpenAPI/Swagger definition file (JSON or YAML) used as input for code generation.

-l, --lang
    Defines the target programming language or generator to use for code output (e.g., `java`, `typescript-angular`, `go`, `python`).

-o, --output
    Sets the directory where the generated client SDK, server stub, or documentation files will be saved.

-c, --config
    Provides a path to a JSON or YAML configuration file that contains generator-specific options and properties.

--additional-properties
    Allows passing additional, comma-separated properties directly to the generator, overriding or adding to its default configurations.

--skip-validate-spec
    Disables the default validation of the input OpenAPI/Swagger specification, useful for working with drafts or non-strict definitions.

--template-dir
    Specifies a directory containing custom Mustache templates to override the default templates for code generation.

swagger-codegen is a powerful command-line tool and library designed to automate the generation of API client SDKs, server stubs, and API documentation from an OpenAPI (formerly Swagger) specification. By consuming a JSON or YAML OpenAPI definition, it can produce boilerplate code in a multitude of programming languages and frameworks, significantly accelerating the development process for both API consumers and providers. Its primary goal is to minimize the amount of manual coding required for API integration, ensuring consistency between the API definition and its consuming/implementing code. This tool is instrumental in promoting an API-first development approach, allowing teams to define their APIs and then automatically generate the necessary code, reducing errors and improving efficiency across the software development lifecycle. It supports a wide array of generators, enabling flexible integration into diverse technology stacks.

It is important to note that the swagger-codegen project has been largely superseded by the OpenAPI Generator, which is a fork created due to differences in development philosophy and governance. As a result, swagger-codegen is less actively maintained and might not support the very latest OpenAPI specification versions or modern language features as comprehensively as its successor. Users seeking the most up-to-date features and ongoing support are often advised to consider OpenAPI Generator instead.

swagger-codegen supports several subcommands beyond `generate` for various tasks:

• `generate`: The most common command, used for generating code.
• `langs`: Lists all available client and server generators supported by the tool. Run `swagger-codegen langs` to see the full list.
• `config-help`: Provides detailed configuration options for a specific generator. For example, `swagger-codegen config-help -l java` shows all Java generator properties.
• `validate`: Validates an OpenAPI/Swagger specification file for correctness.
• `meta`: Generates a new template and configuration files to create a custom generator.

The swagger-codegen tool originated as a key component of the broader Swagger ecosystem, initially developed by Wordnik. It quickly became a popular choice for developers working with RESTful APIs, facilitating rapid code generation from Swagger (OpenAPI) definitions. Over time, as the OpenAPI Specification gained traction and community needs evolved, a significant portion of the community, including core contributors, forked the project to create the OpenAPI Generator in 2018. This fork aimed to accelerate development, improve governance, and better support the evolving OpenAPI Specification. While swagger-codegen continued to exist, its active development and maintenance significantly decreased in favor of the OpenAPI Generator.

openapi-generator-cli(1), curl(1), jq(1)