Mailinglist Archive: yast-devel (163 mails)

< Previous Next >
Re: [yast-devel] WebYast: Documenting REST API - findings
  • From: Cornelius Schumacher <cschum@xxxxxxx>
  • Date: Mon, 7 Sep 2009 12:21:35 +0200
  • Message-id: <200909071221.36079.cschum@xxxxxxx>
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/restility/.

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 <cschum@xxxxxxx>
--
To unsubscribe, e-mail: yast-devel+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: yast-devel+help@xxxxxxxxxxxx

< Previous Next >
References