Swagger is generally pretty adaptable and mostly painless to implement.
The API interface is nice to work with once in place. The RAML approach is
tedious, but might allow a deeper representation of the API.
Swagger 'seems' like the place to start. If it doesn't work to everyone's
expectations, it's minimal sunk cost in the implementation time. Unlike
RAML, which will take quite a bit of time and possibly not end up
substantially more useful than the Swagger-ui generated material.
Thanks,
-Reggie Beckwith
On Fri, Feb 3, 2017 at 1:13 PM, Justin Deoliveira <[email protected]>
wrote:
> 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
>
>
------------------------------------------------------------------------------
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
