Documenting web services API's

Rails
1

Sorry to have to post this again - it was probably under the wrong
subject and went unnoticed.

Is there a standard for providing user documentation for methods that
I expose through we services?

The default documentation (method names and return types) that
appears when the user visits http://localhost:3000/backend/invoke is
concise and correct, but a bit terse. How can I give my users a little
more? Maybe even include an example for them on the same page. Do I
manually insert this in the rendered view? Or is there, like most
things Ruby that I am discovering, a much more elegant way of doing
this using RDoc?

Bealach

2

You’re probably looking for WSDL … anyway if it’s web services you’re
looking at then it’s probably developer documentation, end-users
shouldn’t be touching this at all. The WSDL in ActionWebService is in
http://localhost:3000//service.wsdl by default but u
can change it at routes.rb, but if u’re not sure what WSDL is abt, u
should look it up a bit first in Google.

Bealach Na Bo wrote:

manually insert this in the rendered view? Or is there, like most
things Ruby that I am discovering, a much more elegant way of doing
this using RDoc?

Bealach

Rails mailing list
[email protected]
http://lists.rubyonrails.org/mailman/listinfo/rails

–
Sau S.

http://blog.saush.com
http://read.saush.com
http://jaccal.sourceforge.net

3

Thanks for your comments Sau. My “end users” are developers. The work
in things like Visual Studio and Perl environments. I’m trying to
provide a “black box” service, exposing only the methods (and
documentation for these methods) that they need to talk SOAP/XMLrpc
with my black box that talks to DB back ends.

Basically I want a simple way of integrating the documentation for the
methods that I expose through the web services api into something like
the page that RoR generated for testing the exposed methods. The WSDL
is a little deeper down in the system. The users are already able to
choose a protocol, such as SOAP and use CPAN libraries for Perl to
talk SOAP with my DB back end through my web services api.

Regards,

Bealach

4

On Apr 21, 2006, at 1:09 AM, Bealach Na Bo wrote:

The default documentation (method names and return types) that
appears when the user visits http://localhost:3000/backend/invoke is
concise and correct, but a bit terse. How can I give my users a little
more? Maybe even include an example for them on the same page. Do I
manually insert this in the rendered view? Or is there, like most
things Ruby that I am discovering, a much more elegant way of doing
this using RDoc?

My plan, when this becomes important for our service, is to use some
mixture of RDoc and/or Textile to generate the docs from source.
Semi-literate programming is my friend.

–
~akk