Re: [GeoNetwork-devel] API doc

[Jose G. <jos...@ge...>]

Hi Francois

I don't know other tools for this, this one looks a nice option. If
documentation can be generated automatically, thats really good. Now the
documentation for API requires manual maintenance and is not updated
properly.

+1 for this.

Regards,
Jose García


On Thu, Jan 14, 2016 at 12:55 PM, Francois Prunayre <fx....@gm...>
wrote:

> Hi all, I would like your feedback on API & API documentation.
>
> For Jeeves services we used to have the XML services doc [1] which was
> quite hard to maintain. With the move to Spring MVC, we have now in on
> place in the Java code the description of the service (instead of 2 places
> with Jeeves). It could make sense to try to generate the doc from the Java
> code.
>
> One option could be to use springfox [2] and swagger [3] which allows to
> document the service in the source (with annotations [4]) and generate the
> API doc from that.
>
> An experiment was made in this PR [5] and the API doc could be published
> by the catalog using swagger-ui eg.
> http://apps.titellus.net/gnmdr/swagger-ui/
>
> Before going further, It would be nice to discuss:
> * does this sounds relevant to all ?
> * is there any other/better alternatives ?
> * and if we decide to go that direction, decide on the URL structure and
> make that approach mandatory for all services for future releases.
>
> What do you think ?
>
> Looking forward your feedback.
>
> Francois
>
> [1]
> http://geonetwork-opensource.org/manuals/2.10.4/eng/developer/xml_services/index.html
> [2] http://springfox.github.io/springfox/docs/current/
> [3] http://swagger.io/
> [4]
> https://github.com/fxprunayre/core-geonetwork/blob/improvement/metadata/resources/services/src/main/java/org/fao/geonet/services/api/metadata/resources/ResourcesApi.java#L121
> [5] https://github.com/geonetwork/core-geonetwork/pull/1385
>
>
> ------------------------------------------------------------------------------
> Site24x7 APM Insight: Get Deep Visibility into Application Performance
> APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
> Monitor end-to-end web transactions and take corrective actions now
> Troubleshoot faster and improve end-user experience. Signup Now!
> http://pubads.g.doubleclick.net/gampad/clk?id=267308311&iu=/4140
> _______________________________________________
> GeoNetwork-devel mailing list
> Geo...@li...
> https://lists.sourceforge.net/lists/listinfo/geonetwork-devel
> GeoNetwork OpenSource is maintained at
> http://sourceforge.net/projects/geonetwork
>



-- 













*Vriendelijke groeten / Kind regards,Jose García
<http://www.geocat.net/>Veenderweg 136721 WD BennekomThe NetherlandsT: +31
(0)318 416664 <+31318416664> <https://www.facebook.com/geocatbv>
<https://twitter.com/geocat_bv>
<https://plus.google.com/u/1/+GeocatNetbv/posts>Please consider the
environment before printing this email.*