Use swagger-codegen to generate Java code from Swagger Spec

Swagger is the most popular standard for describing RESTful APIs. The Swagger Specification (formerly known as the OpenAPI Specification) is a JSON or YAML document that describes an API's endpoints, HTTP methods (GET, PUT, POST, etc.), possible responses and fields, possible errors, etc.

Swagger has code generators that will read a Swagger Specification and generate code in a variety of programming languages to consume the API. This saves a lot of time. The command line code generator is a Java Jar file. You need Java 7 or higher installed to run it. There is also a Maven plugin for Java projects that can generate the code for you as part of your project build process.

• swagger-codegen documentation on swagger.io
• swagger-codegen source on GitHub (and documentation on using it)
• swagger-codegen-cli command line utility downloads (Java Jar file)
• swagger-codegen-maven-plugin Maven dependency

You can get help from the command line utility by running:

java -jar swagger-codegen-cli.jar help

which shows:

The most commonly used swagger-codegen-cli commands are:
    config-help   Config help for chosen lang
    generate      Generate code with chosen lang
    help          Display help information
    langs         Shows available langs
    meta          MetaGenerator. Generator for creating a new template set...
    version       Show version information

See 'swagger-codegen-cli help <command>' for more information on a specific command.

If you want detailed help about the generate command:

java -jar swagger-codegen-cli.jar help generate

The code generator can use a local Swagger doc or one hosted on a website. There is a quirk about how it handles URLs.

If the Swagger doc path is a URL and the URL has query parameters in it separated by an ampersand (&), you have to modify the URL slightly depending on whether you are using the command-line utility or the Maven plugin.

Command Line Utility (CLI)

When using swagger-codegen-cli.jar, enclose the -i (or --input-spec) parameter in double quotes if the URL has query parameters, like this:

-i "https://my.api.com/store/api-docs?provider=USER/me&name=MyNewService&version=v1"

For example:

java -jar swagger-codegen-cli.jar generate -l java --library jersey1 -o my/dir --model-package my.model.svc -i "https://my.api.com/store/api-docs?provider=USER/me&name=MyNewService&version=v1"

Maven swagger-codegen-maven-plugin

When using the Maven plugin, substitute & for the & character if the URL has query parameters, like this:

https://mysite.com?color=red&flavor=sweet

Right: ?color=red&flavor=sweet

<configuration>
  <inputSpec>https://mysite.com/api?provider=USER/me&amp;name=MyGreatService&amp;version=v1</inputSpec>
</configuration>

Wrong: ?color=red&flavor=sweet

<configuration>
  <inputSpec>https://mysite.com/api?provider=USER/me&name=MyGreatService&version=v1</inputSpec>
</configuration>

pom.xml

<build>
  <plugins>
    <plugin>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-codegen-maven-plugin</artifactId>
      <version>2.2.1</version>
      <executions>
        <execution>
          <goals>
            <goal>generate</goal>
          </goals>
          <configuration>
            <inputSpec>https://my.api.com/store/api-docs?provider=USER/me&name=MyGreatService&version=v1</inputSpec>
            <language>java</language>
            <configOptions>
              <dateLibrary>joda</dateLibrary>
            </configOptions>
            <library>jersey1</library>
            <modelPackage>my.model.svc</modelPackage>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>