Mailinglist Archive: yast-devel (163 mails)

< Previous Next >
[yast-devel] WebYast: Documenting REST API - findings
  • From: Ladislav Slezak <lslezak@xxxxxxx>
  • Date: Mon, 07 Sep 2009 10:02:20 +0200
  • Message-id: <4AA4BE0C.7090108@xxxxxxx>

Hi all,

Currently we don't have any standard or guidelines how to document Yast REST
API.


Duncan sent me two links:

Rapidoc
-------
(http://code.google.com/p/rapidoc/)


It generates on-line documentation (controller and view) which is part of the
application. The API is documented in the code (inline).

Unfortunately it needs quite a lot of changes (where to search for input files,
where
stote generated files) and the templates need to be modified for our needs.
This seems be not a trivial task...

Anyway, I like the fact that the documentation is provided by the REST server
itself
- the documentation is automatically available (no need to install extra
packages or
search the web) and there is no problem with versions, the documentation will
(or
should) always match the current API on the server.


Vasco
-----
(http://blog.thinkrelevance.com/2008/10/22/introducing-vasco-a-route-explorer-for-rails)

Actually this is not a documentation generator, but it provides a nice GUI to
REST
API (see the link). This would be a good tool for testing during development -
you
should be able to browse the available methods and even test them without need
to
code a frontend first.

Unfortunately it didn't work for me, the page was empty telling me to run a
rake task
to collect the data even though it had been already called and the data file was
present...




I'd like to discuss the REST documentation problem with Karel tomorrow, maybe he
knows better tools...


BTW I found that twitter documentation might be a good example how a REST API
documentation could look like and what it should contain. (See e.g.
http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-search)



--

Best Regards

Ladislav Slez√°k
Yast Developer
------------------------------------------------------------------------
SUSE LINUX, s.r.o. e-mail: lslezak@xxxxxxx
Lihovarsk√° 1060/12 tel: +420 284 028 960
190 00 Prague 9 fax: +420 284 028 951
Czech Republic http://www.suse.cz/
--
To unsubscribe, e-mail: yast-devel+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: yast-devel+help@xxxxxxxxxxxx

< Previous Next >