Swagger Client Code-Generator

Overview

This is a project to build the Swagger code-gen library which can be used to automatically generate client libraries from a Swagger-compliant server. It also contains a testing framework which allows the client library to query an API server and validate expected results You can find out more about both the spec and the framework at http://swagger.wordnik.com. For more information about Wordnik's APIs, please visit http://developer.wordnik.com.

Prerequisites

You need the following installed and available in your $PATH:

- Java 1.6 or greater (http://java.oracle.com)

- Apache ant 1.7 or greater (http://ant.apache.org/)

To build the codegen library

If you don't have the Apache Ivy dependency manager installed, run this build script:

ant -f install-ivy

This will copy the ivy ant lib into your antlib directory. Now you can build the artifact:

ant

This will create the swagger-codegen library in your build folder.

To build a client library

./bin/generate-java-lib.sh {server-url} {api_key} {output-package} {output-dir}

for example:

./bin/generate-java-lib.sh http://petstore.swagger.wordnik.com/api/ special-key com.sample.petstore generated

To build a client library for a different programming language, refer to the

conf/java/templates

folder for sample code templates. The code-gen uses the antlr string template library for generating the output files, please look at http://www.stringtemplate.org for details on the antlr framework.

The files in the

conf/structure

folder are copied by default to the destination directory.

The main class for the generator is at src/main/java/com/wordnik/swagger/codegen/config/java/JavaLibCodeGen.java

The Swagger client test framework

The testing framework helps you to test Swagger generated client libraries using declarative test scripts. The same scripts can be used to test client libraries in different languages. The framework can be used for client and server regression testing.

There are two components in the test framework:

- Test Script

- Test Data

Test script details

Test script is written in JSON structure. The JSON consists of following elements:

Resources. This is a list of resources considered in the test. Each resource object consists of following properties:

- id: a unique test script ID

- name: name of the resource, used in displaying the test result

- httpMethod: HTTP method used in invoking this resource

- path: path of the resource

- suggested method name: By default this refers to method name of the API in resource classes

Test suites. This is a logical way of grouping related test cases. Each test suite consists of following properties:

- id: unique id of the test script, displayed in the test report

- name: name of the test suite. Used in test report

- test cases: List of test cases with in each suite. Each test case consists of following properties:

- id: unique with in the test suite. Used for reporting and tracking output data

- name: Name of the test case

- resource id: references the resource id in the resources section

- input: Input is a JSON object with each property in the object map to query, path or post parameters. For POST data, the name of the property should be supplied as postData. The value for each property can refer to input file or output from previous test cases or actual values.

- assertions: list of assertions that needs to be evaluated after test case is executed.

Each assertion contains

- actual output, specified with reference to output of the current test case using syntax similar to object graph navigation language

- condition , support values are equal (==), not equal (!=), less than (<), lesser than or equal (<=), greater than (>), greater than or equal (>=)

- expected output. Specified using actual values or values referring previous outputs or input data file

Test data file is documented using a Test Data Object which is generated as part of Java client library code-gen. This class provides list getters and setters for each model object available in the resource description. It is called "TestData" and it is available in model package of the java library code generation output.

Chaining results of test cases:

- Reference to data in input file is done with prefix

${input.

, followed by object graph navigation syntax. Example: to refer a first user object in test data file use the syntax

${input.userList[0]}

- To refer a individual property of user object use the syntax

${input.userList[0].username}

- Reference to output of test cases is done using combination test case path and OGNL. Reference to test cases output is prefixed with

${output.

- To refer an output of test case 1 in test suite 2, the syntax will be

${output(1.2)}

. Individual attributes can be accessed using OGNL syntax. Example:

${output(1.1).username}

Reporting Test Results

A Summary will be reported with each test run. For instance:

Sample: "Summary -->  Total Test Cases: 9 Failed Test Cases: 0"

In detail section each test case and its status (passed/failed) are reported. Failures include an exception trace. Test case path is combination of test suite id and test case id separated by "."