Forum: Ruby on Rails Documenting web services API's

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
Bealach Na Bo (Guest)
on 2006-04-21 10:11
(Received via mailing list)
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
Chang Sau S. (Guest)
on 2006-04-23 00:54
(Received via mailing list)
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/<your controller>/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
> removed_email_address@domain.invalid
> http://lists.rubyonrails.org/mailman/listinfo/rails
>
>


--
Sau S.

http://blog.saush.com
http://read.saush.com
http://jaccal.sourceforge.net
Bealach Na Bo (Guest)
on 2006-04-25 12:07
(Received via mailing list)
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
Adam K. (Guest)
on 2006-04-27 02:05
(Received via mailing list)
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
http://therealadam.com
This topic is locked and can not be replied to.