Using Custom Codegen Templates

Last modified on July 21, 2021

Note: This information applies to SwaggerHub On-Premise.

SwaggerHub On-Premise lets you upload custom Swagger Codegen modules for code generation. Custom generators will appear along with the built-in generators in the Export menu. They can be used in source control integrations.

OpenAPI version compatibility

SwaggerHub On-Premise 1.18.8 and later support custom generators for OpenAPI 2.0 and 3.0. Earlier versions of SwaggerHub On-Premise support custom generators for OpenAPI 2.0 only.

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.

Create custom generators

Swagger Codegen uses Java code and template files (Mustache or Handlebars) to transform API definitions into the desired output format. You can create boilerplate code for your custom codegen by using Swagger Codegen CLI, and then customize the code to suit your needs. The code should be compiled into a JAR file, which can then be uploaded to SwaggerHub On-Premise. A single JAR file can contain one or more custom generators.

Prerequisites

  • JDK 8 or later

  • Apache Maven 3.3.3 or later

Mustache vs Handlebars

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:

Create a generator

Follow these steps to create a custom generator:

  1. Download Swagger Codegen CLI:

    swagger-codegen-cli-3.0.25.jar – use it to create OpenAPI 3.0 code generators

    swagger-codegen-cli-2.4.19.jar – use it to create 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

    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:

  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

Upload custom generators

  1. Open the Admin Center.

  2. Select Templates on the left.

  3. Click Browse and select a .jar file containing the compiled generators. Repeat this step to upload more generators.

    Uploading codegen templates

    Click the image to enlarge it.

  4. Select System on the left and click Restart SwaggerHub.

Your custom generator will now appear in the Export menu for API definitions:

Custom codegen templates in the Export menu

Click the image to enlarge it.

in source control integrations:

Custom code generators in source control integrations

Click the image to enlarge it.

and in the Codegen Options dialog:

Custom codegen options

Click the image to enlarge it.

Remove custom generators

To remove a generator, click Remove next to its JAR file in the Admin Center, and then restart SwaggerHub.

Update generators

To replace a generator with a newer version, remove the old JAR file and then upload a new one. Make sure to restart SwaggerHub afterwards.

See Also

Configuring SwaggerHub On-Premise
Generating Code

Highlight search results