Codegen Templates

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

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:

    go.gifswagger-codegen-cli-3.0.34.jarOpenAPI 3.0 code generators

    go.gifswagger-codegen-cli-2.4.27.jarOpenAPI 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:

  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 KOTS Admin Console.

  2. Navigate to Custom Codegen Templates section.

  3. Select Enable custom codegen templates and upload tar.gz file containing custom codegen templates.

    Note

    The file uploaded must be packaged correctly.

    Ensure that:

    • the .jar files of the custom codegen template are in the root directory of the uploaded tar.gz file.

    • the size of the uploaded tar.gz file doesn't exceed 1 MB.

    • in case of using multiple Codegen templates, they are packed into one tar.gz file for an upload in the following format:

      MyCodeGen.tar.gz ¦ {name}-{version}.jar ¦ {name2}-{version2}.jar 

      Once you created the .jar files, package them as follows:

      Sample Command:

      Single .jar file

      tar -zcvf file.tar.gz {name}-{version}.jar 

      Multiple .jar files

      tar -zcvf file.tar.gz *.jar 

      If you already have two custom codegens, to add the third one:

      1. download the existing .tar file.

      2. extract it using tar-xvzf.

      3. add the new .jar file to the directory.

      4. compress it as a new .tar with tar -czvf file.tar.gz directory.

  4. Select Save config once the tar.gz file is uploaded and deploy the latest changes.

    Note

    Ensure the file being uploaded is in the tar.gz format.

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

    Custom codegen templates in the Export menu

    in source control integrations:

    Custom code generators in source control integrations

    and in the Codegen Options dialog:

    Custom codegen options

Remove custom generators

  1. Open KOTS Admin Console.

  2. Navigate to Custom Codegen Templates section.

  3. Disable Enable custom codegen templates.

  4. Select Save config and deploy the latest changes.

Update generators

  1. Open KOTS Admin Console.

  2. Navigate to Custom Codegen Templates section.

  3. Upload tar.gz file containing updated custom codegen templates.

    Note

    Ensure the .jar files of the custom codegen template are in the root directory of the uploaded tar.gz file. The maximum size of the uploaded tar.gz file is limited to 1 MB.

  4. Select Save config and deploy the latest changes.

To list the codegen templates on the system the list-custom-templates operator command can be used.

Usage

kubectl exec -it deploy/swaggerhub-operator [-n NAMESPACE] -- cmd list-custom-templates 

Example

~ ? k exec -it deploy/swaggerhub-operator -n swaggerhub -- cmd list-custom-templates List of custom templates: dara_2_0_custom_codegen_1-swagger-codegen-1.0.0.jar
            dara_2_0_custom_codegen_2-swagger-codegen-1.0.0.jar dara_3_0_custom_codegen_1-swagger-codegen-1.0.0.jar dara_3_0_custom_codegen_2-swagger-codegen-1.0.0.jar 

See Also

Publication date: