A big +1 to swagger. I'm pushing all the projects I'm involved with towards
it, and indeed I'd like a 'next generation' of open standards -> OGC specs
to be conversations around swagger specs, instead of big word documents.
At Planet we started with RAML, but then got a dev who had lots of
experience with all the various tooling and he put us on swagger.
Swagger has a lot more momentum from what I've seen. It's actually evolved
to be https://www.openapis.org/ - they fully opened the spec and it's got a
broad consortium of companies around it, with governance from the Linux
Foundation. So the swagger spec _is_ openapi, and the next iteration will
be done with real open governance.
And it's not a replacement for restlet / jackson or anything like that. I
mean, you can generate from it, but I'd recommend even if there's another
auto-generation route that we still specify the API in swagger. But
there's no moving all documentation to it, it's just provides a few
'extras', like auto-generating clients and interactive api reference. At
Planet we have 'docs <https://www.planet.com/docs/>' (a markdown thing),
and then the 'api-explorer <https://www.planet.com/api-explorer/>' (the
swagger thing).
Sometime soon I hope to get a sort of Restful WFS update using swagger to
specify simpler, more modular endpoints for searching geospatial
information.
On Thu, Feb 9, 2017 at 6:35 AM, Matt Kruszewski <
mkruszew...@boundlessgeo.com> wrote:
> Hi all,
>
> I wanted to add a little bit to the conversation around RAML and Swagger
> that took place in the dev meeting this week.
>
> First, just a little bit about RAML: On its own, like swagger, it's a
> specification for modeling APIs — basically just a yaml document listing
> endpoints, query parameters, request / response body schemas, etc. In both
> cases, what you can do with the spec really depends on the tools
> surrounding it.
>
> With regard to rendering the document as markup, these are the best
> options I’ve seen for each format:
>
> 1. Swagger:
>
> (a.) There are several options for rendering, the most common and
> well-supported of which is the Swagger UI project -- check out
> http://petstore.swagger.io/ to see an example in action. It's not the
> prettiest thing, but it's thorough and allows easy generation of sample
> requests. As Justin said, you could fork this project to add styling. It
> seems like it would be a very useful reference to go along with the
> existing documentation.
>
> (b.) There are several other projects out there for rendering the swagger
> doc to markup, and even merging it with hand-written documentation like
> that currently in the Sphinx docs (e.g., Swagger2Markup:
> https://github.com/Swagger2Markup/swagger2markup). It'd be worth a deeper
> dive to investigate these more thoroughly.
>
> (c.) One thing to note: The output of the online swagger editor (
> http://editor.swagger.io/#/) looks nice, but they haven't actually made
> that template available anywhere else.
>
> 2. RAML:
>
> (a.) The main rendering tool is raml2html (and the related raml2md) -- you
> can see an example of the output here: https://rawgit.com/raml2html/
> raml2html/master/examples/world-music-api.html. Note that it cannot
> automatically generate sample requests like swagger-ui.
>
> (b.) MuleSoft has thrown a lot of weight behind RAML on their AnyPoint API
> Platform, so RAML makes more sense if you’re already on board for that. (I
> was, for another project). They have nice renderers, and use RAML as a
> shared spec for a bunch of different API tools.
>
> As for other differences between them: I think it's best to think of RAML
> as being intended to be written first, as part of API-driven development.
> To that end, they have put a lot of thought into features that make it
> friendly for designing an API by hand. A given endpoint in RAML can inherit
> “traits” and “types”, e.g., “pageable”, “secured”, and “readOnly”, and the
> meaning of those traits at the API level (like a list of common parameters,
> or required headers) would only have to be defined in one shared place.
> Swagger can fully describe the same API, but it lacks those features for
> concisely expressing its higher-level design. (For reference, here is the
> relevant section of the RAML spec: https://github.com/raml-org/
> raml-spec/blob/master/versions/raml-10/raml-10.md/#
> resource-types-and-traits).
>
> On the flip side, the RAML community has not really produced tools for
> automatically generating documentation from code. With Swagger, I've had a
> good experience with a project called Springfox for generating Swagger from
> Spring MVC annotations (this is the same tool Justin mentioned). It isn't
> perfect, but it creates a very useful reference for developers with
> relatively little effort. There is no such project for going from Spring
> annotations to the current version of RAML (1.0). Swagger is a more
> complete platform in that respect, and it seems to me that the ability to
> auto-generate docs would be more useful at this point than a little more
> design expressiveness.
>
> To address one other concern in this thread -- Reggie, what kind of
> performance impact have you noticed on auto-generating Swagger docs from a
> Spring MVC project? It was minimal in my experience (agree with Justin).
>
> Thanks,
> Matt
>
> On Mon, Feb 6, 2017 at 4:37 PM, Jody Garnett <jody.garn...@gmail.com>
> wrote:
>
>> I think this is just for the rest api reference; I would still expect us
>> to provide some api examples in the user guide.
>>
>> I expect we could get swagger to build into the api reference docs into
>> the user/target directory and then cross link from the sphinx user guide
>> (although I note that they have a generator for "confluence wiki" ).
>>
>> --
>> Jody Garnett
>>
>> On 6 February 2017 at 12:50, Mike Pumphrey <m...@boundlessgeo.com> wrote:
>>
>>> 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
>>> m...@boundlessgeo.com
>>> 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 <
>>> > mkruszew...@boundlessgeo.com> 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
>>> >> Geoserver-devel@lists.sourceforge.net
>>> >> 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
>>> Geoserver-devel@lists.sourceforge.net
>>> 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
> Geoserver-devel@lists.sourceforge.net
> 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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
