search

Azure / azure-openapi-validator

Azure Open API Validator
MIT License
47 stars 46 forks source link

Descriptions should be plain text (no HTML tags, no markdown tags, etc) #701

Open Sandido opened 4 months ago

Sandido commented 4 months ago

Lint rule description

<br> cannot be processed by upstream Autorest and SDK doc generators and is therefore not allowed.

Related swagger example

"description": "The query option to fetch Capacity Reservation Group Resource Ids.
<br>'CreatedInSubscription' enables fetching Resource Ids for all capacity reservation group resources created in the subscription.
<br>'SharedWithSubscription' enables fetching Resource Ids for all capacity reservation group resources shared with the subscription.
<br>'All' enables fetching Resource Ids for all capacity reservation group resources shared with the subscription and created in the subscription."

Category

SDK

Severity level

Error

Applies to

Management plane API spec

How to fix the violation

Remove the <br> tags and format your text as plain text.

"description": "The query option to fetch Capacity Reservation Group Resource Ids.
'CreatedInSubscription' enables fetching Resource Ids for all capacity reservation group resources created in the subscription. 
'SharedWithSubscription' enables fetching Resource Ids for all capacity reservation group resources shared with the subscription.
'All' enables fetching Resource Ids for all capacity reservation group resources shared with the subscription and created in the subscription."

What't the impact if breaking the rule

The <br> tags will appear as plain text on all documentation and code upstream of the swagger specs (SDK, client tools). This is confusing to customers and degrades the development experience.

mikeharder commented 3 months ago

@Sandido: Should this be generalized to "Swagger descriptions should be plain-text"? I'm not sure there's an exact definition of what is or isn't "plain-text", but we can try to disallow common mistakes like:

Adding a rule specifically for <br> seems too narrow.

mikeharder commented 3 months ago

@Sandido: Should this be generalized to "Swagger descriptions should be plain-text"? I'm not sure there's an exact definition of what is or isn't "plain-text", but we can try to disallow common mistakes like:

  • HTML tags
  • Markdown formatting
  • URLs? Allow or deny?

Adding a rule specifically for <br> seems too narrow.

@Sandido: Ping

Sandido commented 3 months ago

@mikeharder , Urls seem to work fine: https://learn.microsoft.com/en-us/dotnet/api/azure.resourcemanager.compute.models.virtualmachinehardwareprofile?view=azure-dotnet#properties

https://github.com/Azure/azure-rest-api-specs/blob/main/specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2024-03-01/virtualMachineScaleSet.json#L3839

Html formatting is an issue as seen with the < b r >.

Based on the email thread I shared, I don't think markdown formatting is supported but haven't seen specific instances of this so I can't give a recommendation on that.