In Introduction to Code Generation in RepreZen API Studio we discuss GenTemplates and GenTargets in the context of RAPID-ML models. But as you may know, RepreZen API Studio is a great platform for working with API specifications in Swagger, now officially the OpenAPI Specification. This includes full access to the Swagger Codegen framework.
If you’ve used Swagger Codegen (SCG), you’ll know that the implementation comes with several out-of-the-box modules that generate documentation, client libraries for a variety of languages, and service scaffolding, also geared toward a variety of languages and underlying frameworks. You’ll be glad to know that all of these standard SCG modules are available as GenTemplates in RepreZen API Studio.
As the following screenshots demonstrate, the list of available GenTemplates shown in the New GenTarget wizard depends on the type of the selected model file - Swagger or RAPID-ML.
The GenTarget (
.gen) files that define GenTargets in a model project are YAML files that, among
other things, provide values for parameters that may be used by the GenTemplate. In general, a
GenTemplate declares its parameters including the following information for each parameter:
The name of the parameter
A description of how the parameter will be used
True or false, depending on whether the GenTarget is required to supply a value for the parameter
A default value for the parameter, which is copied into the GenTarget file by the New GenTarget wizard
In the Swagger Codegen framework, SCG modules can declare options which are analagous to GenTemplate parameters, but without required and default properties. The GenTemplates offered by RepreZen API Studio for SCG modules automatically define an optional parameter with no default value for each option declared by the SCG module. For example, here is a portion of a GenTarget based on the Java SCG GenTarget. You can edit this file to provide values for any of the listed parameters.
There are two additional parameters that are available with every SCG GenTemplate, as shown below:
swaggerCodegenConfig parameter is a convenience option; when a complete config file is already
available for the SCG module — as it might be if the same module had been used outside RepreZen API Studio — that file can simply be copied into the
.gen file as the value of this parameter. However, the
same effect could be achieved by copying values to individual parameters in the
swaggerCodegenSystemProperties parameter sets Java system properties that may affect the way
the SCG module operates. These are properties that would be set using the
-D option using the
Swagger Codegen command line interface.
Unused parameters appearing in the wizard-created
.gen file can be deleted to reduce clutter:
because SCG lacks the ability to declare options as required or optional, all parameters in a
corresponding GenTarget are, by definition, optional.
RepreZen API Studio comes prepackaged with all of the standard SCG modules available as GenTargets, but you can also make use of non-standard modules that you create yourself or that you obtain from other sources. In Sharing GenTemplates we describe the ways you can make a GenTemplate available for models in your workspace, namely:
Placing a Java jar file containing the GenTemplate implementation in a model project’s
Placing the jar file in your workspace’s shared GenTemplates folder
Importing a Java project that implements the GenTemplate into your workspace from a variety of sources, including GitHub
The good news for SCG users is that the same mechanisms all work for non-standard SCG modules as well. As long as your module is properly configured to be discoverable by the SCG command line tool, it will also be discoverable by RepreZen API Studio, which will automatically, upon discovery, wrap it into a GenTemplate.
ServiceManagerclass to discover available SCG modules. For a module to be discoverable, the fully-qualified class name of the implementing class must appear on a line by itself in a text resource named
META-INF/services/io.swagger.codegen.CodegenConfig. This resource is typically packaged as part of any SCG module.