Swagger page per internal endpoint

[supersven]

This PR renders a Swagger page per internal endpoint. The benefit is that we don't have to play crazy tricks to get all (overlapping!) paths right. Currently, this is solved in develop by prefixing the paths by their service name (e.g. /<brig>/i/status.)

Executing the swagger operations by clicking on Execute doesn't work and never will: The services do not handle CORS related headers. Thus, the browser refuses to accept the response. But, the rendered curl command works if kubectl forward-port is called as described.

This PR has been inspired by this comment: #3007 (comment)

And, I've removed SwaggerTag, because it's as simple to get its benefits on value level.

Rendered

Checklist

• Add a new entry in an appropriate subdirectory of changelog.d
• Read and follow the PR guidelines

[fisx]

didn't look at the code, just general questions. feel free to ignore me until i've filed a proper review.

And, I've removed SwaggerTag, because it's as simple to get its benefits on value level.

why is value level superior? :) anyway, i'll read it first, then complain.

why does legalhold has its own page?

Currently, this is solved in develop by prefixing the paths by their service name (e.g. //i/status.)

so this PR undoes that solution? (no objection, just asking)

Executing the swagger operations by clicking on Execute doesn't work and never will: The services do not handle CORS related headers. Thus, the browser refuses to accept the response. But, the rendered curl command works if kubectl forward-port is called as described.

did the same limitation hold for the above solution /brig/i/status? if not why is this PR an improvement?

if we decide to live with this limitation (fine by me), we should document on docs.wire.com or (better yet) on the swagger pages in the info heading.

[supersven]

Some answers... 😄
(I'm glad to read your questions as they seem to imply that you're feeling better!)

why is value level superior? :)

IMHO it's easier to understand how the Swagger docs are rendered on value level. Probably, that's a matter of taste.

This change is a bit orthogonal to the rest: I could add data Swagger serviceName port again (I need some port to render the kubectl port-forward port:8080 command in the Swagger description. In theory it could be random, but I was unsure if a random number wouldn't lead to more confusion... 🤔 ).

so this PR undoes that solution?

Yes, no more prefixes as those aren't valid paths. (valid == A path that you may use to query a service.)

did the same limitation hold for the above solution /brig/i/status? if not why is this PR an improvement?

The prefixed paths were not executable at all. The improvement of this PR is that the rendered curl commands are executable (if you ran the rendered kubectl port-forward command before).

Our Servant servers seem to not handle CORS headers. So, we have three options here:

• Teach them CORS
• Setup some HTTP proxy (which knows CORS)
• Document the limitation in the Swagger description at top level

I decided to apply the third option, because it's the simplest. (Finally, this in only about Swagger... 😉 )

why does legalhold has its own page?

Is that wrong? I just found this API and used it without really knowing anything about legalhold... 🙄

[battermann]

Is that wrong? I just found this API and used it without really knowing anything about legalhold...

I'd say, it's wrong. legalhold is not a stand-alone service like brig, galley, etc.

[battermann]

LGTM