easysoa/EasySOA — Issue #83: Documentation and Collaboration in EasySOA
Author: tiry
Created: 2011-12-28 14:36:52+00:00
State: open

EasySOA-registry is based on Nuxeo Platform and does already provide some features for documentation and collaboration around the services definition.

From my point of view there are some possible improvements.

Here is a list of the subjects I see.

The goal is to discuss them and probably create dedicated tickets for the one we decide to implement for real.

## Service Documentation

From what I see in the registry there is very few "user made" documentation about the webservices.

It could make sense to add the same feature as in Nuxeo Platform Explorer where users can create simple documentation (Description, HowTo ...) in a Text/html/Wiki format and associate it to one or several versions of the services.

You can see an example [here](http://explorer.nuxeo.org/nuxeo/site/distribution/current/viewExtensionPoint/org.nuxeo.ecm.platform.usermanager.UserService--userManager/) .
The example page contains some information that is introspected from the service as well as some "user contributed" documentation.

Documentation items are bound to a component/service and associated to a version range so that you can make the documentation evolve with versions without loosing track of the previous versions.

Of course this opens the question of the Web Front end used to browser the services and associated documentation.

Anyway, I can extract from Explorer the needed code and services as a separated module and make it available as a "Service Documentation plugin".

=> Does it sounds interesting ?

## Preview feature

The current easysoa-registry implementation used the built-in feature of Nuxeo for Preview / Annotation.

In the context of a service definition (WSDL) we could greatly improve this :

- make the preview nicer

- either cleanly format and colorize the WSDL

- do a clean HTML rendering of the WDSL

- contribute a versionning policy for the annotations

=> Does it sounds interesting ?

## Diff feature

We are currently thinking of adding to Nuxeo Platform a plugin for managing diff between 2 documents (either on meta-data or Blob Content).

In the EasySOA context this would make sense to be able to diff 2 WSDL or 2 service definitions.

=> Does it sounds interesting ?

## Template based reporting

I recently created a set of Task in NXP to support template based rendering (see [NXP-8201](https://jira.nuxeo.com/browse/NXP-8201) ).

In the context for EasySOA this could be used te generate a report on a given Environment.

This of course need to be digged to define exactly what is required, but this may be a cool feature.

=> Does it sounds interesting ?