REST API Documentation Quirks
This page collects issues and observations related to the Swagger automated REST API documentation tool and its use in the Hilary codebase. There is no particular order or priority to the list below; items were added as they arose.
Swagger doesn't have support for mapped objects such as the response from /api/ui/widgets. Rather, it expects such responses to be formatted as arrays of objects with known keys, e.g.
[
{ "widgetName": "adminheader", "widgetDetails": { /* ... */ } },
{ "widgetName": "confirmdialog", "widgetDetails": { /* ... */ } },
/* ... */
]
instead of the actual response of
{
"adminheader": { /* ... */ },
"confirmdialog": { /* ... */ },
/* ... */
}
As a consequence of this limitation, mapped responses have been documented using the convention of enclosing generic key names in curly braces {}, e.g.
WidgetsConfig {
{widgetName} (WidgetConfig): Configuration data for the named widget
}
https://github.com/wordnik/swagger-spec/issues/38
The Swagger user interface does not support input of more than one instance of a repeatable parameter such as the files query parameter to /api/ui/staticbatch. The live interface only allows a single instance of the query parameter to be included with a request.
https://github.com/wordnik/swagger-ui/issues/118
Some REST endpoints support multiple types for the same input parameter. The /api/tenant/start endpoint, for example, accept as an aliases parameter value either a single string or an array of strings. Swagger does not support this flexibility. Such instances have been documented as arrays of strings.
Swagger does not support compound logic statements as an expression of parameter requirements. A POST request to /api/tenant/{alias}, for example, requires that the body parameter include either a new display name or a new hostname. As there is no way to formally express this requirement using Swagger, both parameters have been formally documented as optional.
Although form parameters are not, in general, optional, Swagger considers the binary contents of an uploaded file as a form parameter. The OAE /api/content/create endpoint only requires binary contents if the new content is of type file, but the user interface designates the binary contents as required in all cases.
Secondary note: the user interface provides a single
<input type="text">control for accepting a file's binary contents, so using the interface to create actual content may be challenging.
Swagger does not allow properties of defined models to support multiple types. For example, the defaultValue property of the model returned in the OAE /api/config/schema endpoint is of a type matched to the particular configuration element (e.g. a Boolean, a text string, etc.). All such properties are currently documented as strings.
It is not possible to define a model as an empty object. Although this capability would seem to be of little use, the configuration values returned by the OAE /api/config/ endpoint all contain a title property that is always (at least for now?) an empty object. Such objects are documented as containing a single null property of type void.