Genio internals

Using genio

genio is being distributed as two ruby gems - genio and genio-parser that run on ruby v1.9.3+. genio-parser is a utility gem that provides parsers for multiple specification formats and genio is the front-ending gem that provides templates and helpers for code generation. In the first release, genio comes with support for 3 languages (php, java and dotnet) and 3 API specification formats (WSDL, WADL and JSON schema).

To generate client libraries, first install genio

  gem install genio

and run one of the following commands depending on the API specification format that you want to work with

genio <php|java|dotnet> --wsdl=path/to/wsdl
genio <php|java|dotnet> --wadl=path/to/wadl
genio <php|java|dotnet> --json-schema=path/to/json-schema

Other options supported by genio are

• --output-path=path/to/output-folder - source files are generated in a folder called output by default. You can use this option to override the destination folder.
• --namespace - genio generates namespaced classes based on package names derived from the API specification file. Use this option to use a different namespace instead.
• --force - Force write existing files without prompting user for confirmation.
• --skip - Skip writing files that already exist in the output path.

The client libraries that are generated by genio work with the core libraries that you find at http://github.com/paypal. You can easily fetch these core libraries using dependency managers in the respective languages (composer, nuget and mvn). See the installation instructions at PayPal's github home for more.

Customizing generated code

genio generates generic classes that can be used as-is in most cases but in case you need minor changes or need to generate additional files, you can easily do so. genio uses the simple but effective .erb files for gnerating files. erb files use a simple syntax that is intuitive at first sight.

To write custom templates,

First head over to the in-built templates to familiarize yourself with erb syntax and understand the data variables that are made available to the template. All templates are in general passed one of the following hashmaps or simple variables -

• schema - a super hashmap containing all the data types defined by the API.
• service - a hashmap containing all operations defined by the API.
• data_type - a hashmap describing the data type that is currently being generated. Contains properties such as description, extends, properties, package etc.
• package - the package under which the current class is to be generated.
• classname - the name under which the current class is to be generated.

You will also notice several helper methods such as validate_class_name, validate_method_name being invoked. These helpers translate names defined in the API to names that are more natural in the respective programming language. For example, names can be pascalcased, camelcased etc.

Next, clone the genio repository

git clone https://github.com/paypal/genio/

Add or edit templates inside the templates folder.

Edit / Add a new task inside the tasks.rb file. The tasks.rb file is the entry point into genio and provides the command line options that you see in the usage section. A typical task

• Creates a new parser object. You can either use the get_parser(options) utility method or hand create a parser object.

        schema = load_schema(options)

                OR

        schema = Parser::Format::Wsdl.new
        load_schema_uri(schema, path)

• Pipes the parsed schema data into a template of choice.

      schema.data_types.each do|name, data_type|
        render("templates/sdk.rest_java.erb",
            :data_type => data_type,
            :classname => name,
            ...
            :create_file => File.join(folder, "#{get_package_folder(package)}/#{validate_file_name(name)}.java"))
      end

Writing custom parsers

A project is worth a thousand words. Head over to the sample project to learn more.