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 a single string. (See following item.)

No Support for Arrays as Form Parameters

The Swagger user interface does not support arrays as form parameters for POST requests. It only allows entry of a single element. If the aliases parameter for /api/tenant/start is documented as an array, for example, only a single value may be provided.

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

There is currently no way to document that a form parameter is optional. The /api/content/reprocessPreviews endpoint, for example, supports the inclusion of optional filters of various types as form parameters in the request body. Even though individual filters are optional, they are documented as required.

No Support for Optional Body Parameters

There is currently no way to document that a body parameter is optional. The /api/content/create endpoint, for example, only requires a link parameter when the user is creating a link. That parameter is not needed for files or collaborative documents, but the Swagger UI requires it in those cases anyway.

This is because swagger expects there only to ever be one body parameter for a request, which is named body and is the full JSON POST body.