# Documenting web services API's **URL:** \ **Category:** Rails\ **Created:** [April 21, 2006, 8:11am UTC](https://www.ruby-forum.com/t/documenting-web-services-apis/58403 "2006-04-21T08:11:15Z")\ **Posts on this page:** 4\ **Page:** 1
**Author:** ![Bealach\_Na\_Bo](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/b/e19b73/32.png) [@Bealach\_Na\_Bo](https://www.ruby-forum.com/u/Bealach_Na_Bo)\ **Post date:** [April 21, 2006, 8:11am UTC](https://www.ruby-forum.com/t/documenting-web-services-apis/58403/1 "2006-04-21T08:11:15Z")
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](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 ---
**Author:** ![Bealach\_Na\_Bo](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/b/e19b73/32.png) [@Bealach\_Na\_Bo](https://www.ruby-forum.com/u/Bealach_Na_Bo)\ **Post date:** [April 22, 2006, 10:54pm UTC](https://www.ruby-forum.com/t/documenting-web-services-apis/58403/2 "2006-04-22T22:54:19Z")
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/](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 > removed\_email\_address@domain.invalid > [http://lists.rubyonrails.org/mailman/listinfo/rails](http://lists.rubyonrails.org/mailman/listinfo/rails) – Sau S. [http://blog.saush.com](http://blog.saush.com) [http://read.saush.com](http://read.saush.com) [http://jaccal.sourceforge.net](http://jaccal.sourceforge.net) ---
**Author:** ![Bealach\_Na\_Bo](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/b/e19b73/32.png) [@Bealach\_Na\_Bo](https://www.ruby-forum.com/u/Bealach_Na_Bo)\ **Post date:** [April 25, 2006, 10:07am UTC](https://www.ruby-forum.com/t/documenting-web-services-apis/58403/3 "2006-04-25T10:07:43Z")
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 ---
**Author:** ![Bealach\_Na\_Bo](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/b/e19b73/32.png) [@Bealach\_Na\_Bo](https://www.ruby-forum.com/u/Bealach_Na_Bo)\ **Post date:** [April 27, 2006, 12:05am UTC](https://www.ruby-forum.com/t/documenting-web-services-apis/58403/4 "2006-04-27T00:05:21Z")
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](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 > **[Adam Keys is typing](https://therealadam.com/)** > > Developer and engineering manager at large