Swagger Codegen

This is the Swagger Codegen project, which allows generation of API client libraries (SDK generation), server stubs and documentation automatically given an OpenAPI Description.

💚 If you would like to contribute, please refer to guidelines and a list of open tasks.💚

📔 For more information, please refer to the Wiki page and FAQ 📔

⚠️ If the OpenAPI Description or Swagger file is obtained from an untrusted source, please make sure you’ve reviewed the artefact before using Swagger Codegen to generate the API client, server stub or documentation as code injection may occur. ⚠️

Versioning

⚠️ this document refers to version 3.X, check here for 2.X.

Both 2.X and 3.X version lines of Swagger Codegen are available and are independently maintained.

NOTES:

Versions 2.X (io.swagger) and 3.X (io.swagger.codegen.v3) have different group ids.
OpenAPI 3.0.X is supported from the 3.X version only

For full versioning info, please refer to the versioning documentation.

Supported Languages and Frameworks

Here’s a summary of the supported languages/frameworks.

API clients: “csharp”, “csharp-dotnet2”, “dart”, “go”, “java”, “javascript”, “jaxrs-cxf-client”, “kotlin-client”, “php”, “python”, “r”, “ruby” “scala”, “swift3”, “swift4”, “swift5”, “typescript-angular”, “typescript-axios”, “typescript-fetch”
Server stubs: “aspnetcore”, “go-server”, “inflector”, “java-vertx”, “jaxrs-cxf”, “jaxrs-cxf-cdi”, “jaxrs-di”, “jaxrs-jersey”, “jaxrs-resteasy”, “jaxrs-resteasy-eap”, “jaxrs-spec”, “kotlin-server”, “micronaut”, “nodejs-server”, “python-flask”, “scala-akka-http-server”, “spring”
API documentation generators: “dynamic-html”, “html”, “html2”, “openapi”, “openapi-yaml”

To get a complete and/or realtime listing of supported languages/frameworks, you can directly query the online generator API or via a cURL command.

1
curl -X 'GET' \
2
  'https://generator3.swagger.io/api/client/V3' \
3
  -H 'accept: application/json'

Check out the OpenAPI Specification for additional information about the OpenAPI project.

Compatibility

The OpenAPI Specification has undergone 3 revisions since initial creation in 2010. The current stable versions of Swagger Codegen project have the following compatibilities with the OpenAPI Specification:

Swagger Codegen Version	Release Date	Swagger / OpenAPI Spec compatibility	Notes
3.0.65 (current stable)	2024-12-18	1.0, 1.1, 1.2, 2.0, 3.0	tag v3.0.65
2.4.44 (current stable)	2024-12-18	1.0, 1.1, 1.2, 2.0	tag v2.4.44

💁 Here’s also an overview of what’s coming around the corner:

Swagger Codegen Version	Release Date	Swagger / OpenAPI Spec compatibility	Notes
3.0.66-SNAPSHOT (current 3.0.0, upcoming minor release) SNAPSHOT	TBD	1.0, 1.1, 1.2, 2.0, 3.0	Minor release
2.4.45-SNAPSHOT (current master, upcoming minor release) SNAPSHOT	TBD	1.0, 1.1, 1.2, 2.0	Minor release

For detailed breakdown of all versions, please see the full compatibility listing.

Getting Started

To get up and running with Swagger Codegen, check out the following guides and instructions:

Once you’ve your environment setup, you’re ready to start generating clients and/or servers.

As a quick example, to generate a PHP client for Swagger Petstore, please run the following:

1
git clone https://github.com/swagger-api/swagger-codegen
2
cd swagger-codegen
3
git checkout 3.0.0
4
mvn clean package
5
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
6
   -i http://petstore.swagger.io/v2/swagger.json \
7
   -l php \
8
   -o /var/tmp/php_api_client

Note: if you’re on Windows, replace the last command with:

1
java -jar modules\swagger-codegen-cli\target\swagger-codegen-cli.jar generate -i http://petstore.swagger.io/v2/swagger.json -l php -o c:\temp\php_api_client

You can also download the JAR (latest release) directly from maven.org.

To get a list of general options available, please run:

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

To get a list of PHP specified options (which can be passed to the generator with a config file via the -c option), please run:

1
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php

Generators

To generate a sample client library

You can build a client against the swagger sample petstore API as follows:

1
./bin/java-petstore.sh

On Windows, run .\bin\windows\java-petstore.bat instead.

This will run the generator with this command:

1
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
2
  -i http://petstore.swagger.io/v2/swagger.json \                               # The location of the Swagger specifcation file (JSON/YAML).
3
  -l java \                                                                     # The desired language for the library.
4
  -o samples/client/petstore/java                                               # The output destination.

You can get the options with the generate --help command (below only shows partial results):

1
NAME
2
        swagger-codegen-cli generate - Generate code with chosen lang
3

4
SYNOPSIS
5
        swagger-codegen-cli generate
6
                [(-a <authorization> | --auth <authorization>)]
7
                [--additional-properties <additional properties>...]
8
                [--api-package <api package>] [--artifact-id <artifact id>]
9
                [--artifact-version <artifact version>]
10
                [(-c <configuration file> | --config <configuration file>)]
11
                [-D <system properties>...] [--git-repo-id <git repo id>]
12
                [--git-user-id <git user id>] [--group-id <group id>]
13
                [--http-user-agent <http user agent>]
14
                (-i <spec file> | --input-spec <spec file>)
15
                [--ignore-file-override <ignore file override location>]
16
                [--import-mappings <import mappings>...]
17
                [--instantiation-types <instantiation types>...]
18
                [--invoker-package <invoker package>]
19
                (-l <language> | --lang <language>)
20
                [--language-specific-primitives <language specific primitives>...]
21
                [--library <library>] [--model-name-prefix <model name prefix>]
22
                [--model-name-suffix <model name suffix>]
23
                [--model-package <model package>]
24
                [(-o <output directory> | --output <output directory>)]
25
                [--release-note <release note>] [--remove-operation-id-prefix]
26
                [--reserved-words-mappings <reserved word mappings>...]
27
                [(-s | --skip-overwrite)]
28
                [(-t <template directory> | --template-dir <template directory>)]
29
                [--type-mappings <type mappings>...] [(-v | --verbose)]
30

31
OPTIONS
32
        -a <authorization>, --auth <authorization>
33
            adds authorization headers when fetching the swagger definitions
34
            remotely. Pass in a URL-encoded string of name:header with a comma
35
            separating multiple values
36

37
...... (results omitted)
38

39
        -v, --verbose
40
            verbose mode

You can then compile and run the client, as well as unit tests against it:

1
cd samples/client/petstore/java
2
mvn package

Other languages have petstore samples, too:

1
./bin/android-petstore.sh
2
./bin/java-petstore.sh
3
./bin/objc-petstore.sh

Generating libraries from your server

It’s just as easy! Use the -i flag to point to either a server or file.

🔧 Swagger Codegen comes with a tonne of flexibility to support your code generation preferences. Checkout the generators documentation which takes you through some of the possibilities as well as showcasing how to generate from local files.

Selective generation

You may not want to generate all models in your project. Likewise you may want just one or two apis to be written, or even ignore certain file formats. If that’s the case check the selective generation instructions.

Advanced Generator Customization

There are different aspects of customizing the code generator beyond just creating or modifying templates. Each language has a supporting configuration file to handle different type mappings, or bring your own models. For more information check out the advanced configuration docs.

Validating your OpenAPI Description

You have options. The easiest is to use our online validator which not only will let you validate your OpenAPI file, but with the debug flag, you can see what’s wrong with your file. Check out Swagger Validator to validate a petstore example.

If you want to have validation directly on your own machine, then Spectral is an excellent option.

Generating dynamic html api documentation

To do so, just use the -l dynamic-html flag when reading a spec file. This creates HTML documentation that is available as a single-page application with AJAX. To view the documentation:

1
cd samples/dynamic-html/
2
npm install
3
node .

Which launches a node.js server so the AJAX calls have a place to go.

Workflow Integration

It’s possible to leverage Swagger Codegen directly within your preferred CI/CD workflows to streamline your auto-generation requirements. Check out the workflows integration guide to see information on our Maven, Gradle, and GitHub integration options. 🚀

Online generators

If you don’t want to run and host your own code generation instance, check our our online generators information.

Contributing

Please refer to this page.

🚧 For swagger-codegen version 3 templates and classes for code generation are being migrated to swagger-codegen-generators repo. In order to know this migration process you can refer this page.

Security contact

Please disclose any security-related issues or vulnerabilities by emailing security@swagger.io, instead of using the public issue tracker.

Thank You

💚💚💚 We’d like to give a big shout out to all those who’ve contributed to Swagger Codegen, be that in raising issues, fixing bugs, authoring templates, or crafting useful content for others to benefit from. 💚💚💚