search

Azure / api-management-developer-portal

Developer portal provided by the Azure API Management service.
MIT License
488 stars 318 forks source link

API specifications - External CSS styles in widgets - Necessary styling not possible #1972

Closed ZarTrox closed 7 months ago

ZarTrox commented 2 years ago

Bug description

In our DevPortal environments we have some APIs that are or will be deprecated and will no longer be supported. To warn our users and partners beforehand we implemented a template for our developers to add to their API specification.

This template references an icon and external css styles from a blob storage. The icon is added to the "deprecation note" but the styles are not applied and therefore the design is messed up.

Deprecation note without styles in the DevPortal: image

Deprecation note with styles in the DevPortal: image

The styles are necessary to highlight this note to make sure the users are aware of the upcoming deprecation.

These Issues talked about the same topic of external css styles not being applied:

It was mentioned that "filtering of the HTML happens by design".

"However, we do understand the problem you're trying to solve, and working on enabling styling of sub-components, so that you'd be able to style practically every element of "Operation details" and other widgets. This, I believe, should address most of the customization questions."

Are there any upcoming changes or news regarding this statement? And will it be possible to style elements from the API specification JSON file, or set a default for all widgets of this type, as styling the widgets for every API is a lot of effort.

As mentioned before the deprecation notes are added in the API specification JSON file and are handled by the responsible teams themselves. It would be essential to add a reliable and consistent feature to add external css styling in DevPortal widgets through the API specifications. Inline css would not be feasible to implement across all teams.

Reproduction steps

  1. Change any API specification code to reference an external .css file with styles
  2. Update the API specification
  3. See in the DevPortal that the styles are not applied (intended behavior)

Expected behavior

Adding external css styling to e.g. the API description in the API specification should be reflected, without breaking other DevPortal styles,

Is your portal managed or self-hosted?

Managed

@AnRei123

ghost commented 2 years ago

@ZarTrox, thank you for opening this issue. We will triage it within the next few business days.

ZarTrox commented 2 years ago

It is important for us to share such a notice and to share a roadmap to the users in the deprecation flag/note. Also the deadline, when the API will be deprecated, needs to be present.

But this is just regarding this specific use-case.

malincrist commented 2 years ago

As mentioned in the issues you provided, we do not support and do not plan to support external CSS.

Are there any upcoming changes or news regarding this statement? And will it be possible to style elements from the API specification JSON file, or set a default for all widgets of this type, as styling the widgets for every API is a lot of effort.

The feature that is discussed here will provide the possibility to style internal elements of the widgets (such as text, buttons, combo boxes etc.): you will be able to style the description of the APIs but that style will be applied for all the descriptions of all the APIs, regardless of the template you provide. This feature is still under development, and we do not have an ETA at this moment. This feature will not provide the possibility to style elements from the API specification json file.

It is important for us to share such a notice and to share a roadmap to the users in the deprecation flag/note. Also the deadline, when the API will be deprecated, needs to be present.

We understand this is important and we are working on the deprecation support: we will support this in Azure Portal and it will be automatically reflected in the Developer Portal. It should be out in a few months.

Regarding how to show deprecation details, you should be able to achieve this behavior by using a custom widget (and implement the logic there). Here you have more details about how to use it.

Hope this helps.

mrcarlosdev commented 7 months ago

This issue is related to managed developer portal. We advise you to create a Azure support request to get assistance on this issue. Please refer to the below link to create a new Azure support request, Please select Problem Type = "Developer Portal" in the request to route it appropriately.

https://learn.microsoft.com/en-us/azure/azure-portal/supportability/how-to-create-azure-support-request