Merge pull request #28 from JuliaComputing/aviks-patch-2

Improve README

README.md

@@ -12,9 +12,11 @@ Check out [OpenAPI-Spec](https://github.com/OAI/OpenAPI-Specification) for addit
 
 ## How do I use this?
 
+The code generation step required by this package is best done on linux. Generated julia code can of course be run on any platform. 
+
 ### Building
 
-To build the project, run this:
+First, you need to build the Swagger Java libraries. Ensure you have Java and maven installed, and the `java` and `mvn` commands available on the path. Then, from the directory where Swagger.jl has been downloads, run this:
 
 ```
 plugin/build.sh
@@ -31,9 +33,16 @@ Note: problems have been reported while building with JDK 9 on MacOS likely beca
 Use the supplied script `plugin/generate.sh` and point it to the specification file and a configuration file. E.g.:
 
 ```
-${SWAGGERDIR}/plugin/generate.sh -i ${SPECDIR}/${SPECFILE} -o ${GENDIR} -c config.json
+${SWAGGERDIR}/plugin/generate.sh config-i ${SPECDIR}/${SPECFILE} -o ${GENDIR} -c config.json
 ```
+_where_
+`SWAGGERDIR` is the location of this package
+`SPECDIR` is the directory where the openapi specification file resides
+`SPECFILE` the name of the openapi specification file from which you are generating Julia code
+`GENDIR` the directory where the generated Julia code will be written
+
+Typically, you would generate the files into a `src` directory for a package. The generated code is ready to be used as a Julia package directly (So long as the package name is passed correctly -- see below)
 
-The configuration file (`config.json`) can have the following options:
+The configuration file (`.json`) can have the following options:
 
 - `packageName`: the Julia package to generate (`SwaggerClient` by default)