Tutorial 2: Coding a Swagger CodeGen Project

Java 7

1. Download Java SE 7 from here. After installation, set JAVA_HOME and JRE_HOME environment variables as per your installation location.
   
   

JAVA_HOME=C:\Program Files\Java\jdk1.7.0_80

JRE_HOME=C:\Program Files\Java\jre7

 

2. Add the following bin locations to the PATH environment variable:
   
   

%JRE_HOME%\bin;

%JAVA_HOME%\bin;

 

Apache Maven 3.0.3 or greater

Go to Apache Maven Download page. Download Binary zip archive and unzip to your local folder, say C:\Tools\apache-maven-3.3.9

MAVEN_HOME=C:\Tools\apache-maven-3.3.9

Add %MAVEN_HOME%\bin to PATH environment variable

 

Install Git

You can install Git for windows from Git - Downloads or you can install Github for windows from https://desktop.github.com/. The later option installs a Github desktop along with Git Shell for all command line operations.

Go to Github - Swagger Code Generator the Github page of this project and copy clone URL.

Open Git Shell, Create a local folder where you want to clone this project, C:\Github for example, and run the following clone command from that folder:

 

Once cloned, run the following command to build the package from the swagger-codegen folder

mvn package

 

After a successful build, lthe following directory structure can be created and some scripts added that can help you generate C# or Java client using this tool and a specified Swagger metadata file.

1. Open a command prompt and go to your local copy of the swagger-codegen project and create the following folders

• mkdir vertafore\metadata—use this folder to store all your swagger-metadata input files.
• mkdir vertafore\client—use this folder to store your generated code.
  
  

Create a batch file in the vertafore folder to set arguments, including a language-specific template location in addition to language, input-metadata-file and output locations.

Name the file: create_rating_csharp_client.bat

1. First, add script similar to what is shown below

set executable=.\modules\swagger-codegen-cli\target\swagger-codegen-cli.jar

If Not Exist %executable% (

mvn clean package

)

set JAVA_OPTS=%JAVA_OPTS% -XX:MaxPermSize=256M -Xmx1024M -DloggerPath=conf/log4j.properties

set ags=generate -t TEMPLATE_DIRECTORY -i SPEC_FILE -l LANGUAGE -o OUTPUT_DIRECTORY

java %JAVA_OPTS% -jar %executable% %ags%

 

2. Then, replace the following parameters with your project's file and folder names and coding language:
   
   

-t <template directory>   This is the name of the folder that contains template files

-i <spec file>    This is the location of the metadata file

-l <language>   This is the client language to generate. For example, csharp

-o <output directory>   This is where to write the generated files (the default is the current directory)

3. Execute this batch file to generate the required client code along with server stubs.

 

1. Open the batch file (create_rating_csharp_client.bat) you created above and update the file to the content shown below:
   
   

set executable=.\modules\swagger-codegen-cli\target\swagger-codegen-cli.jar

If Not Exist %executable% (

mvn clean package

)

set JAVA_OPTS=%JAVA_OPTS% -XX:MaxPermSize=256M -Xmx1024M -DloggerPath=conf/log4j.properties

set ags=generate -t modules\swagger-codegen\src\main\resources\csharp -i vertafore\metadata\ratingApiMetaData.json -l csharp -o vertafore\client\csharp\rating

java %JAVA_OPTS% -jar %executable% %ags%

 

2. Download Rating API metadata from API Developer Portal's API Catalog page.
   
   Click the image to change its size.
   
   
   

3. Store this file in the vertafore\metadata folder and name the file: ratingApiMetaData.json. Make sure you have correct path for this file in your batch file (-i argument value).
4. Run the create_rating_csharp_client.bat file from swagger-codegen folder:
   
   ..\GitHub\swagger-codegen>vertafore\create_ams360_csharp_client.bat
   
   Once complete, you will see the generated files in the vertafore\client\csharp folder. (Our sample uses C# / csharp)

 

Create a batch file for generating Java client.

Name the file create_rating_java_client.bat.

 

1. Update the script in this file as shown below

set executable=.\modules\swagger-codegen-cli\target\swagger-codegen-cli.jar

If Not Exist %executable% (

mvn clean package

)

set JAVA_OPTS=%JAVA_OPTS% -XX:MaxPermSize=256M -Xmx1024M -DloggerPath=conf/log4j.properties

set ags=generate -t modules\swagger-codegen\src\main\resources\java -i vertafore\metadata\ratingApiMetaData.json -l java -o vertafore\client\java\rating

java %JAVA_OPTS% -jar %executable% %ags%

 

2. Run the create_rating_java_client.bat file from swagger-codegen folder

 

..\GitHub\swagger-codegen>vertafore\ create_rating_java_client.bat

 

Once run, you will see the generated files in the vertafore\client\java\rating folder.

 

 

The default settings of this tool are customizable. For example, you can change the package name, IO.Swagger, to Vertafore.Swagger.Rating.

1. Create a config json file and use this while generating files. Name the file something like: csharp_codegen_config.json
   
   

{ "packageName":"Vertafore.Swagger.Rating", "sourceFolder":"Src" }

 

2. Update the script written earlier to point to this file

set ags=generate -t modules\swagger-codegen\src\main\resources\java -i vertafore\metadata\ratingApiMetaData.json -l java -o vertafore\client\java\rating -c YOURPATH\csharp_codegen_config.json

 

Config files are language specific. Also, the packageName cannot be used when generating Java client. Run following command to see what can be configued in this file. java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l LANGUAGE - java or csharp