Remove ?public from API specification

[markylaing]

The ?public endpoints in our swagger documentation are causing confusion even internally. So it likely follows that this is confusing to our users also.

The query parameter is not used anywhere. It’s purpose is solely to define different endpoint behaviours when the caller is trusted vs. untrusted.

We can improve our swagger documentation so that this distinction is made in the endpoint description.

Here is a list of endpoints that need updating:

• GET /1.0
• POST /1.0/auth/identities/tls
• POST /1.0/certificates
• GET /1.0/images/{fingerprint}/export
• GET /1.0/images/{fingerprint}
• GET /1.0/images/aliases/{name}
• GET /1.0/images
• GET /1.0/images?recursion=1
• GET /1.0/operations/{id}/wait
• GET /1.0/operations/{id}/websocket

[markylaing]

Initial investigation for the /1.0 endpoint revealed that it’s not easy to document the return of multiple API types from the same endpoint.

I tried using oneOf but go-swagger didn’t like it:

operation (server_get): yaml: line 28: mapping values are not allowed in this context

[markylaing]

This is more complicated than previously thought.

When an endpoint returns two different responses with the same response code (based on the trusted status of the caller), there is no way to represent this in swagger 2.0 because the oneOf construct is not supported (see https://goswagger.io/go-swagger/reference/models/schemas/#swagger-vs-jsonschema).

We could support this with OpenAPI 3.0, but it doesn't seem easy to generate an OpenAPI 3.0 specification from Golang source.