Hi Matt. I am all about improvements to documentation, and using the right tool for the job, and not being stuck with past decisions.
However, I second a few of Andrea's concerns. Unless we're going to migrate all of our docs to Swagger, how would it work to have documentation build using two different build tools? Do we trust Swagger to be around for a while? That said, API docs and regular docs are kind of different things. I believe it could be possible to have both, a more human-written documentation of the REST API (in our Sphinx docs) and separately a from-the-code generated API docs, kind of like Javadocs I imagine. Thanks, Mike Mike Pumphrey Education Program Director | Boundless 917-338-0407 [email protected] http://boundlessgeo.com @boundlessgeo On 2/3/2017 10:05 AM, Andrea Aime wrote: > HI Matt, > I don't know the tool, but wondering: > > - Is it going to make the REST api documentation into a separate > documentation set as the user docs? > - Can we version it along with GeoServer like we do with the user docs? > - Can it be customized to have the GeoServer colors and logos? > - What about restlets that require longer docs, are these going to be > embedded in the code? > > It's also the first time I see the wiki page. The "Annotation driven" part > scares me quite a bit, can you make > sure the annotation classpath scan is not going to make the startup time > longer? We are constantly fighting to keep > it at bay, we might have to make sure the packages containing > > Cheers > Andrea > > > On Fri, Feb 3, 2017 at 5:55 PM, Matt Kruszewski < > [email protected]> wrote: > >> Hi Mike, >> >> Given the upcoming switch to Spring MVC for the REST API, I wanted to >> start a conversation about possible improvements for the REST documentation >> (GEOS-7931). One option is Swagger, which has a lot of supporting tooling >> and is able to automatically generate docs from Spring MVC annotations -- >> though some additional annotations might be required to flesh things out. >> What experience does everyone have with REST documentation formats and >> tools? >> >> Jody and I are doing some initial research and prototyping, and we have >> gathered our notes so far on the wiki (https://github.com/geoserver/ >> geoserver/wiki/REST-API-Refresh). >> >> Thanks, >> Matt Kruszewski >> >> ------------------------------------------------------------ >> ------------------ >> Check out the vibrant tech community on one of the world's most >> engaging tech sites, SlashDot.org! http://sdm.link/slashdot >> _______________________________________________ >> Geoserver-devel mailing list >> [email protected] >> https://lists.sourceforge.net/lists/listinfo/geoserver-devel >> >> > > ------------------------------------------------------------------------------ Check out the vibrant tech community on one of the world's most engaging tech sites, SlashDot.org! http://sdm.link/slashdot _______________________________________________ Geoserver-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/geoserver-devel
