[api-docs] Polish up the API

[foot]

• Make sure every endpoint that exists is listed but marked as internal
• Resolve inconsistencies in path param names (e.g. workspaceNamespace -> namespace) etc.
• Set the "model" to the default view in the endpoints to show off param descriptions there a bit more clearly.

Other things

• Write internal guide on basic API guidelines, things to check when adding endpoints (that params are documented, are consistent w/ existing endpoints), e.g. document how to preview the api etc (make swagger-docs (?))