Generating REST documentation / WADL and arguments in endpoint methods

[Rachel Lehman]

Hello,

I've been working on generating REST / WADL documentation of our
Endpoints. I picked it up again for the first time since initial
experimentation, now that we have several endpoints running, and
noticed that the only parameter that shows up in the list of
parameters is the MachII event argument, which makes sense because
it's the only cfargument in the function! However, we naturally want
to list possible named arguments.

But then I was reading the WADL documentation wiki entry (http://
trac.mach-ii.com/machii/wiki/WadlDocumentationGenerator) and saw that
the example shows use of cfarguments other than "event". I'm now
wondering how this works with the actual method code?

Should we add non required/unused arguments solely for the purpose of
annotation? Do event arguments get automagically converted to method
arguments when you call a REST endpoint method? Or is this
documentation just outdated? Is there a better way to annotate
endpoint parameters?

Thanks so much for any advice.
-Rachel

[jason.york]

Hi Rachel,

Yes, the event arguments get converted to method arguments when
calling an endpoint. You have the choice of using either (or both).
So you can just declare the event argument if you want and it will be
available. Or you can declare the arguments as shown in the example
you referenced.

It may depend on what version of Mach-ii your running. This feature
has been in BER for quite a while now and we're using it in production
extensively.

Thanks,
-- Jason

[Rachel Lehman]

Very cool. Thanks, Jason! 

-Rachel