Jody/Matt,
You might be better of using the style API rather than the workspace API
for a test / example, as it is rather more straightforward.
Torben
On Fri, Feb 3, 2017 at 1:42 PM, Jeffrey Beckwith <[email protected]
> wrote:
> 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
>
>
------------------------------------------------------------------------------
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
