swagger-codegen generated perl libraries for TroopTrack.

TroopTrack runs on the 1.2 version of the Swagger schema. All existing code that I could find for generating code from the schema and thus having something that is simple to maintain and keep up to date uses 2.0. After wrangling with the tools I decided that the best thing to do would be to generate a 2.0 schema from the 1.2 schema.

The NPM package swagger-tools made this reasonably simple.

1. Modify config.json for your environment:

{
    "api_url":            "https://trooptrack.com:443/api/swagger_doc",
    "java":               "/usr/bin/java",
    "swagger-codegen":    "../swagger-codegen/modules/swagger-codegen-cli/target/swagger-codegen-cli.jar",
    "swagger-tools":      "/opt/local/bin/swagger-tools",
    "swagger2_dir":       "swagger2",
    "swagger2_schema":    "tt.json",
    "swagger12_dir":      "swagger1.2"
}

2. Pull the 1.2 schema, make necessary tweaks, convert to 2, and

$ perl generate.pl

3. Use the generated library:

use strict;
use warnings;
use lib qw( lib );
use Data::Dumper;

# implicitly needs Log::Any
#                  URI::Query
use WWW::SwaggerClient::UsersApi;

my $users = WWW::SwaggerClient::UsersApi->new();

my $partner_token = "<your partner token>";
my $user_token = "<your user token>";

# Get a list of users
# note the relatively mangled method names.  This is a result of the 1.2
# schema nicknames and the swqgger-codegen algorithm.
my $ret = $users->g_et_version_users( 'x_partner_token' => $partner_token,
                                      'x_user_token'    => $user_token );
# $ret contains the json output 
print $ret;

The Conversion from 1.2 to 2.0 is not perfect. A few points:

• The 1.2 schema references 'String'. This is not understood by the converter. I change all instances of 'type': 'String' to 'type': 'string'. This had to happen before the conversion would work.
• The 1.2 schema has implicit return values for most 200s. This in interpreted by swagger-codegen as no return. All operations thaht have a 'void' type have been converted to 'string' in order to get the JSON returned by the API. This then needs to be decoded into perl.

The conversion tool is swagger-codegen

This is a java library that supports the creation of API libraries in many languages including perl. Getting it built and working was tricky, but it is managable by following the instrictions on the referenced site. For reference I am doing it on OS X 10.10.

What is included:

• generate.pl: script to fetch the 1.2 schema, convert it, and generate the perl library
• example.pl: simple example for using the generated libraries to call the API
• lib: directory that holds the perl libs. use libs './lib' to include for testing
• swagger1.2: contains the 1.2 schemas ( pulled directly from TroopTrack )
• swagger2.0: contains the 2.0 schema ( converted and modified as per above )
• config.json: the config file that you should modify for your environment fro running generate.pl

Note that the contents of lib, swagger1.2, and swagger2 are all generated by the generate.pl script. They output of my conversion is included as it is very likley they will work for you out of the box.

• Add api version checking ( is this in there implicitly already? )
• Add testing