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

?

1 2 3

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

Wrong: ?color=red&flavor=sweet

?

1 2 3

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

pom.xml

?

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

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