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.

No Support for Mapped Objects

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

No Support for Repeated Parameters

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

No Support for Flexible Types

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.

No Support for Compound Logic in Parameter Requirements

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.

No Support for Optional Form Parameters

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.

No Support for Flexible Model Types

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.