Remove "Definition" section from the API details web widget view

[AnRei123]

Bug description

The definition parts within the Swagger files are important to be able to generate client proxy source code based for an API.

Typically, the definition content can either be retrieved for every API version from a standardized endpoint (URL postfix) or by downloading the Swagger file in Yaml or Json format from the DevPortal

BUT for most of the API consumers, this information is not of high interest when studying the API scope and to implement the API request in their code.

Instead the "Definition" contents in the API details widget blow up the page length and irritate portal user due to the redundant content in regard to the examples in the response section above the definition sub chapter. For getting a quick overview about the details of an API, the "Definition" is in this user context not of value, but it is more hindering to quickly get the important contents out from the API details page.

Why did you add the Definition section to the API details page of the new DevPortal. In the legacy portal, the Definition contents had not be displayed in a dedicated sub chapter of the API details page.

Here an example screenshot that shows how the definition content is currently reflected in the API details web widget:

Expected behavior

Please do not display the Definition contents on the API details web widget. Remove the definition section from the web widget and thus from the API details pages.

Remark: Of course, the definition contents must still be be part of the Swagger files.

Is your portal managed or self-hosted?

Managed

Environment

• Operating system: Windows 10
• Browser: Google (latest)

[mikebudzynski]

@AnRei123 Which of the options below would you consider the best solution?

a. Collapse the Definitions section by default and let the portal visitors expand it, or b. Remove the Definitions section altogether for all APIs on the developer portal, or c. Display the Definitions section on a separate page

[AnRei123]

Thank you very much for proposing the three options. I asked my colleagues for their opinion. Option a) or c) would be fine. Option (c) might be the preferred solution from UX perspective. But I assume that option (a) means less initial and maintenance efforts on both ends, your development and our content management.

So we would vote for option (a): Collapse the Definitions section by default and let the portal visitors expand it

[MortenKartevoll]

Is there an ETA on this?

I agree with @AnRei123 that option (a) would be the best solution if one should be implemented. That said, in the long run, it would be nice if there could be an option to configure this, meaning the owners of the API could choose between the 3 different options.

The image provided in the bug description does not, in my opinion, describe how bloated the API page could become. Imagine that you have a couple of lines of description related to the Response and Request contracts. In addition, the body can certainly contain many properties leading to a huge amount of bloated and duplicated data since the definitions are available in the respective endpoints using them.

[mikebudzynski]

@MortenKartevoll At this moment there is no ETA. Is this an urgent issue for you?

[MortenKartevoll]

I am in a position where it is bloating the API documentation of our developer portal so it is important to me:) That said, it is not crucial for our documentation since it can be pushed to the bottom of the page.

I guess what I am saying is yes, but I understand that there are probably more important issues!