Codegen Templates

Download Swagger Codegen CLI:

swagger-codegen-cli-3.0.34.jar –OpenAPI 3.0 code generators

swagger-codegen-cli-2.4.27.jar –OpenAPI 2.0 code generators

Run the following command to create a boilerplate project for your codegen (replace the arguments with your values):

java -jar path/to/swagger-codegen-cli-VERSION.jar meta -o OUT_DIR -n CODEGEN_NAME -p com.mycompany.openapi.codegen

Where the arguments are:

meta is a command to create a project for a custom generator.

-o OUT_DIR specifies the output directory where the project will be created. The default directory is the current folder.

-n CODEGEN_NAME specifies the name of your custom generator that will be displayed in SwaggerHub’s Export menu. This name must differ from the built-in generator names. You can use this command to see the built-in generator names:

java -jar path/to/swagger-codegen-cli-VERSION.jar langs

-p PACKAGE specifies the package name of your generator class. The default package is io.swagger.codegen.

The generated project includes a Java class that implements the generator, sample .mustache templates, pom.xml (Maven configuration file), and a README file.

Modify the generator code and .mustache templates to suit your needs. For some tips, see:

(Optional.) If your code uses custom dependencies not covered by Swagger Codegen, you need to package these dependencies into your final JAR file. You can do this by using the Maven Assembly Plugin. Add the following to the plugins section of your pom.xml:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-assembly-plugin</artifactId>
  <version>3.1.1</version>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>single</goal>
      </goals>
      <configuration>
        <descriptorRefs>
          <descriptorRef>jar-with-dependencies</descriptorRef>
        </descriptorRefs>
      </configuration>
    </execution>
  </executions>
</plugin>

Build the project by running the following command in the project’s root directory:

mvn package

This will create the {name}-{version}.jar file (or {name}-{version}-jar-with-dependencies.jar if the Maven Assembly Plugin is used) in the target subdirectory. This is the file you will need to upload to SwaggerHub.

Before uploading your generator to SwaggerHub, test it locally to make sure it works correctly and produces the expected output. In the command below, replace the -l argument with your generator name, -o with the desired output directory, and -i with your API definition path or URL. Use io.swagger.codegen.Codegen if you are testing OpenAPI 2.0 templates with Swagger Codegen 2.x, and io.swagger.codegen.v3.Codegen if you are testing OpenAPI 3.0 templates with Swagger Codegen 3.x.

On Mac and *nix:

java -cp /path/to/swagger-codegen-cli-VERSION.jar:/path/to/your.jar \
     io.swagger.codegen.Codegen \
     -i http://petstore.swagger.io/v2/swagger.yaml \
     -l CODEGEN_NAME \
     -o GENERATED_DIR

On Windows, use ; instead of : as a separator in the -cp argument, and write the whole command on one line (line breaks are added for readability):

java -cp path\to\swagger-codegen-cli-VERSION.jar;path\to\your.jar
     io.swagger.codegen.Codegen
     -i http://petstore.swagger.io/v2/swagger.yaml
     -l CODEGEN_NAME
     -o GENERATED_DIR