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

💚 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 2.X, check here for 3.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 information, please refer to the versioning documentation.

Supported Languages and Frameworks

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 out OpenAPI-Spec for additional information about the OpenAPI project.

Table of contents

• 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

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:

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

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:

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

git clone https://github.com/swagger-api/swagger-codegen
cd swagger-codegen
mvn clean package
java -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 from maven.org

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

java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar help 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

Generators

To generate a sample client library

You can build a client against the swagger sample petstore 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 the help generate command (below only shows partial results):