Repository files navigation

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

💚 If you would like to contribute, please refer toguidelines and a list ofopen tasks.💚

📔 For more information, please refer to theWiki page andFAQ 📔

⚠️ 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 ascode injection may occur.⚠️

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

Both2.X and3.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) havedifferent group ids.
• OpenAPI 3.0.X is supported from the 3.X version only.

For full versioning information, please refer to theversioning documentation.

Currently, the following languages/frameworks are supported:

• API clients:ActionScript,Ada,Apex,Bash,C# (.net 2.0, 3.5 or later),C++ (cpprest, Qt5, Tizen),Clojure,Dart,Elixir,Elm,Eiffel,Erlang,Go,Groovy,Haskell (http-client, Servant),Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured),Kotlin,Lua,Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations)Objective-C,Perl,PHP,PowerShell,Python,R,Ruby,Rust (rust, rust-server),Scala (akka, http4s, swagger-async-httpclient),Swift (2.x, 3.x, 4.x, 5.x),Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
• Server stubs:Ada,C# (ASP.NET Core, NancyFx),C++ (Pistache, Restbed),Erlang,Go,Haskell (Servant),Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework,PKMST),Kotlin,PHP (Lumen, Slim, Silex,Symfony,Zend Expressive),Python (Flask),NodeJS,Ruby (Sinatra, Rails5),Rust (rust-server),Scala (Finch,Lagom, Scalatra)
• API documentation generators:HTML,Confluence Wiki
• Configuration files:Apache2
• Others:JMeter

Check outOpenAPI-Spec for additional information about the OpenAPI project.

• Versioning
• Compatibility
• Getting Started
• Generators
  • To generate a sample client library
  • Generating libraries from your server
  • Validating your OpenAPI Spec
  • Generating dynamic html api documentation
  • Generating static html api documentation
• Workflow Integration
• Online Generators
• Contribution
• Swagger Codegen Core Team

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

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

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

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

• Prerequisites
• Building
• Using Docker

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 forhttps://petstore.swagger.io/v2/swagger.json, you can run the following:

git clone https://github.com/swagger-api/swagger-codegencd swagger-codegenmvn clean packagejava -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \   -i https://petstore.swagger.io/v2/swagger.json \   -l php \   -o /var/tmp/php_api_client

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

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

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

To get a list ofgeneral options available, you can run the following:

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jarhelp generate

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

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

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

./bin/java-petstore.sh

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

This will run the generator with this command:

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \  -i https://petstore.swagger.io/v2/swagger.json \  -l java \  -o samples/client/petstore/java

with a number of options. You can get the options with thehelp generate command (below only shows partial results):

NAME        swagger-codegen-cli generate - Generate code with chosen langSYNOPSIS        swagger-codegen-cli generate                [(-a <authorization> | --auth <authorization>)]                [--additional-properties <additional properties>...]                [--api-package <api package>] [--artifact-id <artifact id>]                [--artifact-version <artifact version>]                [(-c <configuration file> | --config <configuration file>)]                [-D <system properties>...] [--git-repo-id <git repo id>]                [--git-user-id <git user id>] [--group-id <group id>]                [--http-user-agent <http user agent>]                (-i <spec file> | --input-spec <spec file>)                [--ignore-file-override <ignore file override location>]                [--import-mappings <import mappings>...]                [--instantiation-types <instantiation types>...]                [--invoker-package <invoker package>]                (-l <language> | --lang <language>)                [--language-specific-primitives <language specific primitives>...]                [--library <library>] [--model-name-prefix <model name prefix>]                [--model-name-suffix <model name suffix>]                [--model-package <model package>]                [(-o <output directory> | --output <output directory>)]                [--release-note <release note>] [--remove-operation-id-prefix]                [--reserved-words-mappings <reserved word mappings>...]                [(-s | --skip-overwrite)]                [(-t <template directory> | --template-dir <template directory>)]                [--type-mappings <type mappings>...] [(-v | --verbose)]OPTIONS        -a <authorization>, --auth <authorization>            adds authorization headers when fetching the swagger definitions            remotely. Pass in a URL-encoded string of name:header with a comma            separating multiple values...... (results omitted)        -v, --verbose            verbose mode

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

cd samples/client/petstore/javamvn package

Other languages have petstore samples, too:

./bin/android-petstore.sh./bin/java-petstore.sh./bin/objc-petstore.sh

It's just as easy--just 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 thegenerators documentation which takes you through some of the possibilities as well as showcasing how to generate from local files and ignore file formats.

You may not want to generateall models in your project. Likewise you may want just one or two apis to be written. If that's the case check theselective generation instructions.

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 theadvanced configuration docs.

You have options. The easiest is to use ouronline validator which not only will let you validate your spec, but with the debug flag, you can see what's wrong with your spec. For example check outSwagger Validator.

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

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:

cd samples/dynamic-html/npm installnode.

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

To do so, just use the-l html flag when reading a spec file. This creates a single, simple HTML file with embedded css so you can ship it as an email attachment, or load it from your filesystem:

cd samples/html/open index.html

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

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

Please refer to thispage

Swagger Codegen core team members are contributors who have been making significant contributions (review issues, fix bugs, make enhancements, etc) to the project on a regular basis.

Members of the core team shoulder the following responsibilities:

• Provides guidance and direction to other users
• Reviews pull requests and issues
• Improves the generator by making enhancements, fixing bugs or updating documentations
• Sets the technical direction of the generator

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

The Swagger Codegen project is intended as a benefit for users of the Swagger / Open API Specification. The project itself has theLicense as specified. In addition, please understand the following points:

• The templates included with this project are subject to theLicense.
• Generated code is intentionallynot subject to the parent project license

When code is generated from this project, it shall be consideredAS IS and owned by the user of the software. There are no warranties--expressed or implied--for generated code. You can do what you wish with it, and once generated, the code is your responsibility and subject to the licensing terms that you deem appropriate.

💚💚💚 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 usefulcontent for others to benefit from. 💚💚💚