[yast-devel] WebYast: Documenting REST API - findings
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...) 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@suse.cz 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@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On Monday 07 September 2009, Ladislav Slezak wrote:
Currently we don't have any standard or guidelines how to document Yast REST API.
The openSUSE Build Service and SUSE Studio use a tool to create the
documentation from a simple text file specifying the API, and a set of files
with example responses (mostly XML). The tool can be found here:
https://forgesvn1.novell.com/svn/opensuse/trunk/buildservice/docs/api/restil....
One example how the generated docs look like is here:
http://susestudio.com/help/api/v1.
It's a pretty simple process and documenting the API in a central text file
has the advantage that everything is in one place. More dynamic approaches
getting the docs from the code itself have the disadvantage that they either
need tuning or might not expose what you want to expose, and providing
example data is harder.
--
Cornelius Schumacher
On 7.9.2009 12:21, Cornelius Schumacher wrote:
On Monday 07 September 2009, Ladislav Slezak wrote:
Currently we don't have any standard or guidelines how to document Yast REST API.
The openSUSE Build Service and SUSE Studio use a tool to create the documentation from a simple text file specifying the API, and a set of files with example responses (mostly XML). The tool can be found here: https://forgesvn1.novell.com/svn/opensuse/trunk/buildservice/docs/api/restil.... One example how the generated docs look like is here: http://susestudio.com/help/api/v1.
Thanks! This looks great! The documentation format is simple and it should be easy to document our REST API using restility. I'd like to integrate it into WebYaST, do you have an RPM package available somewhere? If we use it in WebYaST we will need an RPM package in OBS, but I haven't found it there. (BTW 'rake package' fails, it seems that some files are missing in the SVN repository, e.g. lib/restility.rb and the version file.) -- Best Regards Ladislav Slezák Yast Developer ------------------------------------------------------------------------ SUSE LINUX, s.r.o. e-mail: lslezak@suse.cz 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@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On 7.9.2009 10:02, Ladislav Slezak wrote: [...]
Vasco ----- [...] 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...
JFYI: I found that the data generator correctly finds all routes (even in plugins), but the problem is that the details are read via ActiveRecord::Base class. That means it cannot work with our ActiveResource plugins, it has been designed for database based applications :-( -- Best Regards Ladislav Slezák Yast Developer ------------------------------------------------------------------------ SUSE LINUX, s.r.o. e-mail: lslezak@suse.cz 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@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On 8.9.2009 13:28, Ladislav Slezak wrote:
I'd like to integrate it into WebYaST, do you have an RPM package available somewhere? If we use it in WebYaST we will need an RPM package in OBS, but I haven't found it there.
(BTW 'rake package' fails, it seems that some files are missing in the SVN repository, e.g. lib/restility.rb and the version file.)
I managed to create a gem for restility and a rake task for WebYast which reads REST documentation from restdoc/ subdirectory in a plugin and generates HTML output to public/<name>/restdoc. (The same static overlay as in the web-client is needed.) The documentation is then directly available on the REST service server (e.g. http://localhost:8080/system/restdoc/index.html). The generated HTML cannot be used in wiki directly (if we want to put the same documenation online). Manual tuning is needed or I could create a wiki output formatter (I guess that should be quite easy, there are already HTML and text output filter classes). What do you think about it? -- Best Regards Ladislav Slezák Yast Developer ------------------------------------------------------------------------ SUSE LINUX, s.r.o. e-mail: lslezak@suse.cz 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@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On Thursday 10 September 2009 10:36:11 Ladislav Slezak wrote:
The generated HTML cannot be used in wiki directly (if we want to put the same documenation online). Manual tuning is needed or I could create a wiki output formatter (I guess that should be quite easy, there are already HTML and text output filter classes).
Wiki's are for human editable text. For hosted docu we can host it somewhere and link to it. But I like the overall solution. -- Duncan Mac-Vicar P. - Engineering Manager, YaST SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nuernberg) -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On Mon, Sep 07, 2009 at 12:21:35PM +0200, Cornelius Schumacher wrote:
The openSUSE Build Service and SUSE Studio use a tool to create the documentation from a simple text file specifying the API, and a set of files with example responses (mostly XML). The tool can be found here: https://forgesvn1.novell.com/svn/opensuse/trunk/buildservice/docs/api/restil.... One example how the generated docs look like is here: http://susestudio.com/help/api/v1.
Could you link also the restility source for the studio API, so that we know how to write our own docs? -- Martin Vidner, YaST developer http://en.opensuse.org/User:Mvidner Kuracke oddeleni v restauraci je jako fekalni oddeleni v bazenu -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
participants (4)
-
Cornelius Schumacher -
Duncan Mac-Vicar Prett -
Ladislav Slezak -
Martin Vidner