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):

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