wadl2go

README

#+TITLE: wadl2go
#+AUTHOR: Katherine Cox-Buday

wadl2go parses a .wadl file and emits a go client.

Usage:
#+BEGIN_SRC sh :results scalar :exports results
  wadl2go 2>&1
#+END_SRC

#+RESULTS:
: Usage of wadl2go:
:   -base-url="": Specifies a replacement for the given base URL.
:   -debug=false: Controls debug log messages
:   -package-name="main": Specifies the package the generated file will be under.
:   -to-file="": Specifies the destination file
:   -wadl-file="": Specifies which file to parse

* Requirements

Rendering the output execs the gojson tool to generate go structs for json data. This must be installed, and $GOPATH/bin must be on your path:

#+BEGIN_SRC sh
  go get github.com/ChimeraCoder/gojson/gojson
#+END_SRC

The go xml parser does not understand DTDs. If the input file uses these, the wadl input will need preprocessing to resolve external entities and replace them. For example:

#+BEGIN_SRC sh
  xmllint --loaddtd --noent --dropdtd example.wadl > example-noent.wadl
#+END_SRC

* Disclaimer

Currently, this is just a wonderfully hacky thing I coded up in a few days to generate a client for Openstack's [[http://docs.openstack.org/developer/cinder/][Cinder]]. Because of ambiguities in the WADL format, it can be difficult to reliably generate code without relying on some inference. This inference is very nascent at the moment.

Much work could be done to improve this tool; however, I thought this might help someone out if it wasn't sitting on my computer bit-rotting.

* Caveats
- wadl2go only considers JSON requests and response types.
- If you include files in the grammar sections, wadl2go makes some assumptions about the content of these files.
  - Currently only .json files are supported, and wadl2go assumes these are JSON Schema files.
  - How these files are referenced is unfortunately not covered by the WADL specification. wadl2go currently looks for the "json:ref" attribute and will cross-reference the URI specified with URI's specified in the grammar file.

- wadl2go only consumes  1 doc element per representation.
- Documentation is currently poorly scrubbed for XML elements in an attempt to derive plain ASCII documentation. UTF documentation was not considered.
- The autogenerated code is not formatted, nor are requisite imports added. It assumes you will format the standard Go tooling to take care of this.
- The responses are currently derived from JSON examples. This produces unwieldy anonymous structures. This will be fixed in the very near future.

* Suggested Improvements

** General

**** TODO [[file:render.go::{{/*%20TODO(katco-):%20Don't%20ignore%20error%20here%3B%20look%20at%20num%20of%20items%20in%20response%20collection%20*/}}][Don't ignore JSON parse errors in HTTP responses.]]
These are useful feedback as to whether or not the response is reasonable. wadl2go should inspect the return type to determine if JSON deserialization is warranted.
**** TODO Clean up this mess of a codebase.
**** TODO Support XML representations.
**** TODO Support > 1 documentation blocks for each representation.
**** TODO [[file:render.go::/%20TODO(katco-):%20Correctly%20reference%20the%20auto-generated%20structure%20type.][When rendering variable types, correctly reference the auto-generated structure type.]]
**** TODO Support automatic gofmt.

** Inference

**** TODO Look at all attributes on response/request representations and attempt to find URI's that match grammar elements.

**** TODO Examine included grammar files to better determine what format we're looking at.