I've had some success with documenting the "representation" classes with Javadoc and then using a tool that understands Spring MVC annotations to generate HTML documentation from the code, that way the REST API docs stay in sync with the code. The onus though is on the developer working on that portion of the REST API to ensure that good documentation is written up in the Javadoc.
I have done this successfully with RESTdoclet. This way you get full coverage of all the REST API resources available; what operations are allowed for those resources, the query parameters, and request body parameters all generated from the code (Spring MVC annotations) and Javadoc. There are several other tools that do this. Then leave it up to the community to add REST API usage examples as they discover more use cases for how they use it. My two cents, --Steve -----Original Message----- From: Rahkonen Jukka (Tike) [mailto:[email protected]] Sent: Wednesday, September 10, 2014 6:41 AM To: '[email protected]' Subject: [Geoserver-users] How to improve documentation of REST? Hi, REST is probably the most common topic on this list. This search finds 5208 mails: http://sourceforge.net/p/geoserver/mailman/search/?q=REST I interpret that REST interests users but it is difficult to use and documents that we have do not cover enough use cases. We have documentation in http://docs.geoserver.org/stable/en/user/rest/index.html and http://docs.geoserver.org/stable/en/user/rest/api/index.html#rest-api and usage examples in http://docs.geoserver.org/stable/en/user/rest/examples/index.html#rest-examples Documentation is not bad but obviously it should be made better. Any suggestions about how to improve it? I believe that is should be something community driven or community assisted because developers are busy with other things and getting funding for improving documentation is just a dream. -Jukka Rahkonen- ------------------------------------------------------------------------------ Want excitement? Manually upgrade your production database. When you want reliability, choose Perforce Perforce version control. Predictably reliable. http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk _______________________________________________ Geoserver-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/geoserver-users ------------------------------------------------------------------------------ Want excitement? Manually upgrade your production database. When you want reliability, choose Perforce Perforce version control. Predictably reliable. http://pubads.g.doubleclick.net/gampad/clk?id=157508191&iu=/4140/ostg.clktrk _______________________________________________ Geoserver-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/geoserver-users
