Skip to content

REST API Documentation Quirks

Stephen A Thomas edited this page Jun 20, 2014 · 13 revisions

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 Input 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.

No Support for Empty Objects as Models

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.

Clone this wiki locally