Easier debugging of swagger doc rendering

[CarsonCook]

Is your feature request related to a problem? Please describe. I sometimes help debug why a swagger document doesn't render properly in the API Catalog. It is not easy, there is not good logging to show how the swagger doc is queried and transformed by the API Catalog server, and there is no information in the UI except for sometimes a very generic error that it could not be retrieved.

Describe the solution you'd like Better logging server side, ideally without requiring debug mode (errors should be logged regardless).

I'd also like better information in the UI. Sometimes there is an error message in the UI, but it is usually not actually relevant and is always the same error message. Sometimes the substitute swagger is shown (e.g. if no swaggerUrl is present), but we should also indicate why the substitute was shown (error retrieving swagger vs no url given).

Describe alternatives you've considered

Additional context

[balhar-jakub]

@plavjanik I am moving the suggested improvements here:

The second problem is that the problem was not in those values. Can the message be accurate and more specific, for example:

The Swagger definition was retrieved but was not a valid JSON document. + message from the parser
The Swagger definition was retrieved but it was not a valid Swagger JSON document according to the schema + message from parser
The URL (https://the url/) is not a valid URL
The URL could not be accessed + HTTP client error + what to fix
The server has provided a certificate (details about certificate) that is not trusted by API ML, following certificate and CAs are trusted: ... See documentation ... for more information on how to establish trust between API ML and the API.
other causes that I have not listed...

The last message is actually the root cause of the problem that the extender had and the expected behavior. In the case of the extender, the API ML enabler used a correct certificate but the HTTPS server used a different one because of an upgrade of another library. The bug in that library is not an API ML issue, but the misleading and not helpful error message is.

The current plan is to get to at lest some of the improvements within 22PI2 for Zowe.