API Documentation/Publishing - Slate vs Swagger


#1

Hi @andrius, @snaiste

a few versions ago, the HAT API documentation was published in Swagger. The latest version uses Slate.

Any reason for the change? The Noggin team is picking out an API publishing system, so we are just wondering what quirks you may have encountered.

Terry


#2

Hi @Terry_Lee,

With the API growing it was becoming increasingly difficult to write the Swagger spec and maintain it really. The biggest benefit of Swagger is their UI (SwaggerUI) that can be used to show a working version of the API, however in the end it wasn’t worth it.

The biggest pain point was the way of describing data models which didn’t have enough flexibility really - you couldn’t use the same data model for request and response and actually demonstrate that the fields change (the optional date_created and last_updated are filled out by most endpoints for example). There was also no satisfactory support for model composition (as you know quite a few models have other models as part of them), especially for such cases where you have no object or a single object, or a list of objects. This could be worked around by specifying separate models for each case, but then in the UI they are also presented as different, which is not true and overall becomes more confusing than helpful.

So the verbosity of swagger meant all the work of writing everything manually, plus the extra effort of writing everything according to the document spec, minus potential benefits of doing so in our case. With Slate it is all just markdown text with code examples grouped according to language.