I’ve used swagger (with the springfox library) on a springmvc project with
pretty good results. I am not sure it’s a replacement itself for the
end-user documentation we have, but they would definitely provide a very
useful tool for exploring the api. A few points.
- You are able to have it only scan particular packages for annotations, so
if you put all your controllers in a single package hierarchy I’ve found
the scanning time to be negligible
- In order to theme the documentation you need to fork the swagger-ui
project and do whatever theming and styling you deem fit if you’re not
happy with the default UI. What i’ve done on other projects is:
1. fork the swagger-ui <https://github.com/swagger-api/swagger-ui>
repository into our organization
2. apply the styling and logo changes required
3. add a pom file that packages up the resources as a jar that can easily
be depended on via maven
- The docs are kind of implicitly versioned because they are driven from
annotations in our code. That said the swagger model supports the notion of
a “version” if you version your api separately from the rest of the codebase
-Justin
On Fri, Feb 3, 2017 at 11:07 AM Andrea Aime <[email protected]>
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
>
>
>
>
> --
> ==
> GeoServer Professional Services from the experts! Visit
> http://goo.gl/it488V for more information.
> ==
>
> Ing. Andrea Aime
> @geowolf
> Technical Lead
>
> GeoSolutions S.A.S.
> Via di Montramito 3/A
> 55054 Massarosa (LU)
> phone: +39 0584 962313 <+39%200584%20962313>
> fax: +39 0584 1660272 <+39%200584%20166%200272>
> mob: +39 339 8844549 <+39%20339%20884%204549>
>
> http://www.geo-solutions.it
> http://twitter.com/geosolutions_it
>
> *AVVERTENZE AI SENSI DEL D.Lgs. 196/2003*
>
> Le informazioni contenute in questo messaggio di posta elettronica e/o
> nel/i file/s allegato/i sono da considerarsi strettamente riservate. Il
> loro utilizzo è consentito esclusivamente al destinatario del messaggio,
> per le finalità indicate nel messaggio stesso. Qualora riceviate questo
> messaggio senza esserne il destinatario, Vi preghiamo cortesemente di
> darcene notizia via e-mail e di procedere alla distruzione del messaggio
> stesso, cancellandolo dal Vostro sistema. Conservare il messaggio stesso,
> divulgarlo anche in parte, distribuirlo ad altri soggetti, copiarlo, od
> utilizzarlo per finalità diverse, costituisce comportamento contrario ai
> principi dettati dal D.Lgs. 196/2003.
>
>
>
> The information in this message and/or attachments, is intended solely for
> the attention and use of the named addressee(s) and may be confidential or
> proprietary in nature or covered by the provisions of privacy act
> (Legislative Decree June, 30 2003, no.196 - Italy's New Data Protection
> Code).Any use not in accord with its purpose, any disclosure, reproduction,
> copying, distribution, or either dissemination, either whole or partial, is
> strictly forbidden except previous formal approval of the named
> addressee(s). If you are not the intended recipient, please contact
> immediately the sender by telephone, fax or e-mail and delete the
> information in this message that has been received in error. The sender
> does not give any warranty or accept liability as the content, accuracy or
> completeness of sent messages and accepts no responsibility for changes
> made after they were sent or for other risks which arise as a result of
> e-mail transmission, viruses, etc.
>
> -------------------------------------------------------
>
> ------------------------------------------------------------------------------
> 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
