Codegen Templates

SwaggerHub On-Premise 2.6.0 and later support custom generators for OpenAPI 2.0 and 3.0.

Generators created with Swagger Codegen 2.x are used for OpenAPI 2.0 definitions, and generators created with Swagger Codegen 3.x are used for OpenAPI 3.0 definitions.

• JDK 8 or later

• Apache Maven 3.3.3 or later

Swagger Codegen 2.x uses the Mustache templating engine whereas 3.x uses the Handlebars engine. The template file extension is the same (.mustache), but the processing engine is different. Handlebars is a superset of Mustache, which means it supports the Mustache syntax and adds some extra features. Keep the differences in mind when creating templates for both OpenAPI 2.0 and 3.0, or when migrating OpenAPI 2.0 templates (Mustache) to OpenAPI 3.0 (Handlebars).

To learn more about the Mustache and Handlebars syntax and about the differences, see:

• Mustache syntax (also supported by Handlebars)

• Handlebars-specific syntax

• Swagger Codegen: Mustache template variables

• Swagger Codegen: Differences between Mustache and Handlebars syntax

Follow these steps to create a custom generator:

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

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

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

   • the project’s README file

   • How to add a generator for a new language or framework

   • Building your own templates

   • Mustache template variables and Differences between Mustache and Handlebars syntax

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

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

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