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 <[email protected]> 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 <[email protected]> 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
>> [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
>>
>
>
------------------------------------------------------------------------------
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
