swagger-codegen

swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.

16,964

6,037

16,964

3,423

View on GitHub

Top Related Projects

openapi-generator

21,595

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

slate

36,069

Beautiful static documentation for your API

prism

4,272

Turn any OpenAPI2/3 and Postman Collection file into an API server with mocking, transformations and validations.

widdershins

1,504

OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown

Quick Overview

Swagger Codegen is an open-source tool that generates server stubs, client SDKs, and API documentation from OpenAPI (formerly Swagger) specifications. It supports a wide range of programming languages and frameworks, allowing developers to quickly create API-first applications and services.

Pros

Supports numerous programming languages and frameworks
Generates both client and server code from a single OpenAPI specification
Customizable templates for fine-tuning generated code
Active community and regular updates

Cons

Generated code may require manual refinement for production use
Learning curve for customizing templates and configurations
Some languages and frameworks have better support than others
Large codebase can make it challenging to contribute or debug issues

Code Examples

Generating a Java client:

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

Generating a Python Flask server:

java -jar swagger-codegen-cli.jar generate \
  -i https://petstore.swagger.io/v2/swagger.json \
  -l python-flask \
  -o ./python-flask-server

Generating TypeScript-Angular client:

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

Getting Started

Download the latest swagger-codegen-cli.jar from the GitHub releases page.
Run the following command to generate code:

java -jar swagger-codegen-cli.jar generate \
  -i <path-to-your-swagger-spec> \
  -l <target-language> \
  -o <output-directory>

Replace <path-to-your-swagger-spec> with the URL or file path to your OpenAPI specification, <target-language> with your desired language/framework, and <output-directory> with the desired output location.
Navigate to the output directory and follow the generated README.md for further instructions on using the generated code.

Competitor Comparisons

openapi-generator

21,595

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

Pros of openapi-generator

More active development and frequent updates
Supports a wider range of programming languages and frameworks
Better documentation and community support

Cons of openapi-generator

Steeper learning curve for newcomers
May have more breaking changes due to frequent updates

Code Comparison

swagger-codegen:

public class PetApi {
    private ApiClient apiClient;

    public PetApi() {
        this(Configuration.getDefaultApiClient());
    }
}

openapi-generator:

public class PetApi {
    private final ApiClient apiClient;

    public PetApi(ApiClient apiClient) {
        this.apiClient = apiClient;
    }
}

The main differences in the code snippets are:

openapi-generator uses a final keyword for the apiClient field
openapi-generator's constructor takes an ApiClient parameter
swagger-codegen has a no-arg constructor that uses a default ApiClient

Both projects aim to generate client libraries, server stubs, and documentation from OpenAPI (formerly Swagger) definitions. openapi-generator is a fork of swagger-codegen that has since evolved independently. While both tools serve similar purposes, openapi-generator generally offers more features, better performance, and wider language support. However, swagger-codegen may be simpler for beginners and have fewer breaking changes between versions.

api-blueprint

8,648

API Blueprint

Pros of API Blueprint

Uses a simple, human-readable Markdown-based syntax
Focuses on design-first API development
Supports a wide range of tools and integrations

Cons of API Blueprint

Less widely adopted compared to Swagger/OpenAPI
Limited code generation capabilities
Fewer language-specific tools and libraries available

Code Comparison

API Blueprint example:

# GET /users/{id}
+ Response 200 (application/json)
    {
        "id": 1,
        "name": "John Doe"
    }

Swagger-Codegen (OpenAPI) example:

/users/{id}:
  get:
    responses:
      '200':
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                name:
                  type: string

Key Differences

Syntax: API Blueprint uses Markdown, while Swagger-Codegen uses YAML or JSON
Tooling: Swagger-Codegen offers more extensive code generation capabilities
Ecosystem: Swagger-Codegen has a larger community and more third-party tools
Learning curve: API Blueprint is generally easier to learn and read
Flexibility: Swagger-Codegen provides more detailed API specifications

Both tools have their strengths, with API Blueprint excelling in simplicity and readability, while Swagger-Codegen offers more comprehensive features and wider adoption in the industry.

slate

36,069

Beautiful static documentation for your API

Pros of Slate

Focuses on creating beautiful, customizable API documentation
Easier to set up and use for non-developers
Provides a more visually appealing out-of-the-box solution

Cons of Slate

Limited to documentation generation, unlike Swagger Codegen's broader capabilities
Less flexibility in terms of input formats and programming languages
May require more manual effort for complex API structures

Code Comparison

Slate (Ruby):

require 'middleman'
require 'middleman-syntax'
require 'middleman-autoprefixer'
require 'middleman-sprockets'
require 'rouge'
require 'redcarpet'

Swagger Codegen (Java):

import io.swagger.codegen.*;
import io.swagger.models.Swagger;
import io.swagger.parser.SwaggerParser;

public class CustomGenerator extends DefaultGenerator {
    // Custom generator implementation
}

Slate is primarily designed for creating API documentation, using Ruby and Markdown to generate static HTML pages. It offers a clean, three-column layout that's easy to navigate and customize.

Swagger Codegen, on the other hand, is a more comprehensive tool that generates server stubs, client SDKs, and documentation for various programming languages based on OpenAPI (Swagger) specifications. It's more versatile but may have a steeper learning curve for non-developers.

While Slate excels in producing visually appealing documentation quickly, Swagger Codegen offers broader functionality for API development and integration across multiple platforms and languages.

prism

4,272

Turn any OpenAPI2/3 and Postman Collection file into an API server with mocking, transformations and validations.

Pros of Prism

Lightweight and fast mock server for API development and testing
Supports dynamic mocking and request validation out of the box
Easy to set up and use with minimal configuration

Cons of Prism

Limited code generation capabilities compared to Swagger Codegen
Focused primarily on mocking and validation, not full API lifecycle management
Less extensive language support for client/server code generation

Code Comparison

Prism (CLI usage):

prism mock api.yaml

Swagger Codegen (CLI usage):

java -jar swagger-codegen-cli.jar generate \
  -i api.yaml \
  -l java \
  -o ./generated

Key Differences

Prism is designed for API mocking and validation, making it ideal for rapid prototyping and testing. It excels in creating mock servers quickly with minimal setup.

Swagger Codegen, on the other hand, focuses on generating client SDKs and server stubs across multiple programming languages. It offers more comprehensive code generation capabilities but requires more configuration.

While Prism provides a streamlined experience for API mocking, Swagger Codegen offers broader language support and more extensive customization options for code generation.

Choose Prism for quick API mocking and validation during development, and Swagger Codegen for generating client libraries and server stubs across various programming languages.

widdershins

1,504

OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown

Pros of Widdershins

Supports multiple API description formats (OpenAPI, AsyncAPI, Semoasa)
Generates documentation in various formats (Markdown, Slate, Shins)
Lightweight and faster for simple documentation generation tasks

Cons of Widdershins

Limited to documentation generation, unlike Swagger Codegen's broader scope
Less extensive language support for code generation
Smaller community and fewer contributors compared to Swagger Codegen

Code Comparison

Widdershins (JavaScript):

const widdershins = require('widdershins');
let options = {};
widdershins.convert(apiDefinition, options)
  .then(output => console.log(output))
  .catch(err => console.error(err));

Swagger Codegen (Java):

CodegenConfig config = new JavaClientCodegen();
ClientOptInput input = new ClientOptInput().config(config);
input.setOpenAPI(parseOpenAPISpec(specFile));
DefaultGenerator generator = new DefaultGenerator();
generator.opts(input).generate();

While Widdershins focuses on documentation generation from API specifications, Swagger Codegen offers a broader range of functionality, including code generation for various programming languages and frameworks. Widdershins is more lightweight and specialized in creating documentation, while Swagger Codegen provides a comprehensive toolkit for API development and integration.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

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 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.

Versioning
Compatibility
Getting Started
Generators
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:

Swagger Codegen Version	Release Date	Swagger / OpenAPI Spec compatibility	Notes
3.0.64 (current stable)	2024-11-07	1.0, 1.1, 1.2, 2.0, 3.0	tag v3.0.64
2.4.43 (current stable)	2024-08-09	1.0, 1.1, 1.2, 2.0	tag v2.4.42

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

Swagger Codegen Version	Release Date	Swagger / OpenAPI Spec compatibility	Notes
3.0.65-SNAPSHOT (current 3.0.0, upcoming minor release) SNAPSHOT	TBD	1.0, 1.1, 1.2, 2.0, 3.0	Minor release
2.4.44-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 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):

NAME
        swagger-codegen-cli generate - Generate code with chosen lang

SYNOPSIS
        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/java
mvn package

Other languages have petstore samples, too:

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

Generating libraries from your server

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

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. 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 Spec

You have options. The easiest is to use our online 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 out Swagger Validator.

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:

cd samples/dynamic-html/
npm install
node .

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

Generating static html api documentation

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

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

Swagger Codegen Core Team

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

Security contact

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

License information on Generated Code

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

The templates included with this project are subject to the License.
Generated code is intentionally not subject to the parent project license

When code is generated from this project, it shall be considered AS 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.

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. ððð

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of openapi-generator

Cons of openapi-generator

Code Comparison

Pros of API Blueprint

Cons of API Blueprint

Code Comparison

Key Differences

Pros of Slate

Cons of Slate

Code Comparison

Pros of Prism

Cons of Prism

Code Comparison

Key Differences

Pros of Widdershins

Cons of Widdershins

Code Comparison

Convert designs to code with AI

README

Swagger Codegen

Versioning

Supported Languages and Frameworks

Table of contents

Compatibility

Getting Started

Generators

To generate a sample client library

Generating libraries from your server

Selective generation

Advanced Generator Customization

Validating your OpenAPI Spec

Generating dynamic html api documentation

Generating static html api documentation

Workflow Integration

Online Generators

Contributing

Swagger Codegen Core Team

Security contact

License information on Generated Code

Thank You

Top Related Projects

Convert designs to code with AI