Ginger

Enrich your generated API document with samples, to describe your API more precise, vivid and easy to be understood.

Tutorials

I. Swagger your document

The precondition for using Ginger is that you have followed Swagger's Tutorials and made your service works happily with Swagger -- At least pass the Test in the tutorial.

Thus, start your service and you can hit the swagger resource declaration url:

http://www.example.com:8080/your/api/path/api-docs.json

This is your swaggerBaseURL, keep it in mind.

II. Prepare your Sample Package

A sample package is a directory in which there're several Request Files and one Sequence File. There's a sample package in code base's test resources you can refer to.

1. Request File

Request File is a UTF-8 encoded text file which describes your HTTP request intuitively, one request file should only represent one request.

Here's an example:

A POST request with Accept and Content-Type headers, as well as a JSON body and goes to /shopping-cart

POST /shopping-cart
> Accept: application/json
> Content-Type: application/json
{ "items": [
  {
    "url": "/shopping-cart/1",
    "product":"2ZY48XPZ",
    "quantity": 1,
    "name": "New socks",
    "price": 1.25
  } ]
}

For more details and usages of the Request File, please see the wiki

2. Sequence File

Sequence File is a UTF-8 encoded text file used to control the flow of requests we descibed in Request Files.

Its name is a constant called sample.seq

Here'e an example:

// add some itmes in the shopping cart
items << PostItems.req

// get the item which id is the first one in the previous items 
selectedItemA << GetItem.req $items[0].id

selectedItemB == GetItem.req $items[1].id

// update the item's count to 0
updateItem << PutItem.req $selectedItemA:ETag $selectedItemA.id 0

//delete the item
deleteItem << DeleteItem.req $updateItem:ETag $updateItem.id

For more details and usages of the Sequence File, please see the wiki

III. Launch Ginger

Ginger is an executable all-in-one jar package ginger-0.1-jar-with-dependencies.jar, there're 2 ways to get it:

Download the source and launch mvn package
Download the binary directly from Bintray

Assume you've done the above steps:

Your swaggerBaseURL is http://www.example.com:8080/api/api-docs.json ,
You've prepared your Request Files and Sequence File in a sample package located at /foo/samples/

Now, prepare a json configuration file for Ginger:

{
   "swaggerBaseURL":"http://www.example.com:8080/api/api-docs.json",
   "apiBasePath": "/api",
   "samplePackage":"/foo/samples",
   "outputTemplatePath":"https://raw.github.com/kongchen/api-doc-template/master/v1.1/markdown.mustache",
   "outputPath":"doc.md",
   "withFormatSuffix":"false"
}

swaggerBaseURL must be end with api-docs.json, as defined in Swagger. In another word, it should be configured as swagger.api.basepath in
outputTemplatePath is the document output template's URI, see more in api-doc-template
apiBasePath is the api's path based on the server's root endpoint. This configuration is very important for populating the samples in output document.
outputPath is the final document's ouput path.
withFormatSuffix indicates if you wannt swagger's .{format} suffix in your document.
samplePackage is the directory you prepared.

Note that this item can omit and if so, no samples would be generated and added in to your document. In another word, you'll get a same document just like you run Swagger-Maven-Plugin locally.

Assume the configuration file is test.json, now you can launch Ginger:

java -jar ginger-0.1-jar-with-dependencies.jar test.json

to let Ginger:

Generate API document,
Run samples you described in the samplePackage,
Automatically populate the samples' results in the document according to the output template.

Finally, check out the doc.md to see the final document when the launch finished successfully.

kongchen / ginger