diff --git a/README b/README deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/README.md b/README.md new file mode 100644 index 000000000000..8aaa56829558 --- /dev/null +++ b/README.md @@ -0,0 +1,134 @@ +# 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 "." + \ No newline at end of file diff --git a/build.xml b/build.xml index 2bc3490544fe..39d677684941 100644 --- a/build.xml +++ b/build.xml @@ -30,6 +30,27 @@ + + + + + + + + + + + + + + + + + + + + + @@ -41,7 +62,7 @@ - +