forked from loafle/openapi-generator-original
Merge branch 'master' of github.com:wordnik/swagger-codegen
This commit is contained in:
rpidikiti
134
README.md
Normal file
134
README.md
Normal file
@@ -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:
|
||||
|
||||
<li>- Java 1.6 or greater (http://java.oracle.com)
|
||||
|
||||
<li>- 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:
|
||||
|
||||
<pre>
|
||||
ant -f install-ivy
|
||||
</pre>
|
||||
|
||||
This will copy the ivy ant lib into your antlib directory. Now you can build the artifact:
|
||||
|
||||
<pre>
|
||||
ant
|
||||
</pre>
|
||||
|
||||
This will create the swagger-codegen library in your build folder.
|
||||
|
||||
|
||||
### To build a client library
|
||||
|
||||
<pre>
|
||||
./bin/generate-java-lib.sh {server-url} {api_key} {output-package} {output-dir}
|
||||
</pre>
|
||||
|
||||
for example:
|
||||
<pre>
|
||||
./bin/generate-java-lib.sh http://petstore.swagger.wordnik.com/api/ special-key com.sample.petstore generated
|
||||
</pre>
|
||||
|
||||
To build a client library for a different programming language, refer to the <pre>conf/java/templates</pre> 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 <pre>conf/structure</pre> 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:
|
||||
|
||||
<li>- Test Script
|
||||
|
||||
<li>- 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:
|
||||
|
||||
<li>- id: a unique test script ID
|
||||
|
||||
<li>- name: name of the resource, used in displaying the test result
|
||||
|
||||
<li>- httpMethod: HTTP method used in invoking this resource
|
||||
|
||||
<li>- path: path of the resource
|
||||
|
||||
<li>- 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:
|
||||
|
||||
<li>- id: unique id of the test script, displayed in the test report
|
||||
|
||||
<li>- name: name of the test suite. Used in test report
|
||||
|
||||
<li>- test cases: List of test cases with in each suite. Each test case consists of following properties:
|
||||
|
||||
<li>- id: unique with in the test suite. Used for reporting and tracking output data
|
||||
|
||||
<li>- name: Name of the test case
|
||||
|
||||
<li>- resource id: references the resource id in the resources section
|
||||
|
||||
<li>- 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.
|
||||
|
||||
<li>- assertions: list of assertions that needs to be evaluated after test case is executed.
|
||||
|
||||
Each assertion contains
|
||||
|
||||
<li>- actual output, specified with reference to output of the current test case using syntax similar to object graph navigation language
|
||||
<li>- condition , support values are equal (==), not equal (!=), less than (<), lesser than or equal (<=), greater than (>), greater than or equal (>=)
|
||||
<li>- 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:
|
||||
|
||||
<li>- Reference to data in input file is done with prefix <pre>${input.</pre>, followed by object graph navigation syntax.
|
||||
Example: to refer a first user object in test data file use the syntax <pre>${input.userList[0]}</pre>
|
||||
|
||||
<li>- To refer a individual property of user object use the syntax <pre>${input.userList[0].username}</pre>
|
||||
|
||||
<li>- Reference to output of test cases is done using combination test case path and OGNL. Reference to test cases output
|
||||
is prefixed with <pre>${output.</pre>
|
||||
|
||||
<li>- To refer an output of test case 1 in test suite 2, the syntax will be <pre>${output(1.2)}</pre>. Individual attributes can
|
||||
be accessed using OGNL syntax. Example: <pre>${output(1.1).username}</pre>
|
||||
|
||||
#### Reporting Test Results
|
||||
|
||||
A Summary will be reported with each test run. For instance:
|
||||
|
||||
<pre>
|
||||
Sample: "Summary --> Total Test Cases: 9 Failed Test Cases: 0"
|
||||
</pre>
|
||||
|
||||
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 "."
|
||||
|
||||
23
build.xml
23
build.xml
@@ -30,6 +30,27 @@
|
||||
</classpath>
|
||||
</taskdef>
|
||||
|
||||
<target name="clean" description="cleans the project folder">
|
||||
<mkdir dir="build" />
|
||||
<echo message="deleting build files" />
|
||||
<delete quiet="true">
|
||||
<fileset dir="build">
|
||||
<include name="*.jar" />
|
||||
<include name="*.xml" />
|
||||
</fileset>
|
||||
</delete>
|
||||
|
||||
<delete dir="build/main" quiet="true" />
|
||||
|
||||
<!-- libraries handled by ivy -->
|
||||
<echo message="deleting libs handled by ivy" />
|
||||
<delete>
|
||||
<fileset dir="lib">
|
||||
<include name="*.jar" />
|
||||
<include name="*.zip" />
|
||||
</fileset>
|
||||
</delete>
|
||||
</target>
|
||||
|
||||
<target name="resolve" description="retreive dependencies with ivy">
|
||||
<delete>
|
||||
@@ -41,7 +62,7 @@
|
||||
<ivy:retrieve pattern="${basedir}/lib/[artifact]-[revision].[ext]" conf="build" />
|
||||
</target>
|
||||
|
||||
<target name="compile" description="builds the module without artifact resolution or cleaning">
|
||||
<target name="compile" depends="resolve" description="builds the module">
|
||||
<echo message="building ${module}-${version.identifier}.${artifact.ext}"/>
|
||||
<delete quiet="true" file="build/${module}-*.jar" />
|
||||
<mkdir dir="build" />
|
||||
|
||||
Reference in New Issue
Block a user