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:
- 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.
- 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.garnett@anonymised.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 <mike@anonymised.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
mike@anonymised.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 <
mkruszewski@anonymised.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@anonymised.comrge.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@anonymised.comrge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
)