Click on internal link in OpenApi spec leads to empty `api-details` / `operation-details`

[MarvinVaillant]

Bug description

Using internal HTML links for navigation within an OpenAPI spec leads "No operation selected." message in api-details / operation-detailswidgets.

Reproduction steps

1. Create a minimal OpenApi yaml file as follows:

   openapi: 3.0.1
   info:
   title: Test API
   description: |-
   <a href="#overview">Overview</a>
   <!-- some other description -->
   <h3 id="overview">Overview</h3>
   <p>Some overview</p>
   version: "V1"
   paths:
   /test/path:
   get:
     summary: A test endpoint
     responses:
       200:
         description: "Request successful"

2. In the developer portal management ui create a new page containing the api-list (Dropdown) widge, a api-details widget and operation-details widget
3. Save and publish
4. Open the just created page in the developer portal as a "normal" user (not the management ui)
5. Select the API in the dropdown (and refresh page [required due to bug 2421])
6. Click on the Link "Overview"
7. Content of operation-details widget is "No operation selected"
8. Refresh page again (probably required due to bug 2421]
9. Content of api-details widget is "the specific api does not exist"

Expected behavior

Clicking on internal links scrolls the page to the referenced heading.

Is your portal managed or self-hosted?

Managed

Environment

• Operating system: MacOS
• Browser: Firefox
• Version: 122.0.1

Additional context

Seems like currently URI fragment (part behind the #) is used to select specified api and operation. After selecting an API the URI look like https://<domain>/<path>#api=test-api&operation=test-operation. Once we click on the link in the OpenAPI spec, the URI looks like this https://<domain>/<path>#overview.

Also the following screenshot shows that the id attribute is removed from the h3 element and therefore link cannot work.

[malincrist]

Hi @MarvinVaillant , thanks for reaching out!

Embedding HTML in API specification files, such as OpenAPI files, is generally considered a bad practice - API specs should focus on describing the API’s functionality, endpoints, parameters, and responses, while HTML, on the other hand, deals with presentation and user interaction.

The id attribute is removed from the h3 element, due to Developer Portal's restrictions - introducing an element with an 'id' attribute may interfere with the Developer Portal's logic. Hence, we only allow a few attributes that may be needed for styles.

Can you please share why you need something like this? Is there anything that we can improve about the API Details widget that may help in your situation?

[MarvinVaillant]

Hey @malincrist, thanks for the response.

Some of our API specs contain extensive descriptions. That's why we often use links to other sections of the description or create table of contents. Is there any other way we could achieve this?

[malincrist]

In this case, I believe you should be able to achieve this behavior with custom widgets. (more info here) You could implement a widget to replace the default API: Details widget. Hope this helps!

[sthirthala]

Please log managed portal issues to Azure support team using Support + Help link in Azure portal and select Problem Type = Developer portal.

[sthirthala]

Please log managed portal issues to Azure support team using Support + Help link in Azure portal and select Problem Type = Developer portal.