[mashup-dev] Attaching human-readable description to a service

[Thilina Gunarathne]

+1 for the idea..  I prefer supporting documentation on each operation
level.

This can be a good start to add an API documentation for the service in
widgets as well as in the TryIt? Console...  How about inventing another
"service_url?" option called "?doc" or "?apidoc" to present these API docs
in a good format.

I found good service API documentation to be a critical piece in the mashup
world.. Specially the restafarians seems to prefer good human readable
documentation rather than machine readable service descriptions.. 

 

Thanks,

Thilina

  _____  

From: mashup-dev-bounces at wso2.org [mailto:mashup-dev-bounces at wso2.org] On
Behalf Of Jonathan Marsh
Sent: Tuesday, May 08, 2007 10:31 PM
To: mashup-dev at wso2.org
Subject: [mashup-dev] Attaching human-readable description to a service

 

In the Mashup Server UI, we need to allow some human-readable annotation on
a service.  As simple as "this service is a smoke test."  How should this
documentation be attached to a service?

 

-          It should appear in <wsdl:documentation> elements, but we don't
want to force users to hand-edit WSDL in order to add documentation.

-          It could appear in the .js in some format - but that seems likely
to be unwieldy.

-          It could be set in the UI.

 

I'm tending towards the last option - with the documentation appearing in
the WSDL as well.

 

What granularity should the documentation be allowed on?  How about on a
service, and on each operation, for now.

 

I can imagine simply clicking on the documentation for a service or
operation, and if I have appropriate permissions, being able to edit that
description in place (ala flickr titles and descriptions.)

 

Jonathan Marsh -  <http://www.wso2.com> http://www.wso2.com -
<http://auburnmarshes.spaces.live.com> http://auburnmarshes.spaces.live.com

 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://wso2.org/pipermail/mashup-dev/attachments/20070509/33801a16/attachment.htm