search

Azure / azure-openapi-validator

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

[new rule]: Checking path parameter name consistency #388

Open ArcturusZhang opened 2 years ago

ArcturusZhang commented 2 years ago

Lint rule description

For instance we have a path:

/subscriptions/{subsId}/resourceGroups/{rgName}/providers/Microsoft.Compute/virtualMachines/{name}

and any sub-path whose parent is this path, should have exactly the same prefix as the above path, including the variable names.

/subscriptions/{subsId}/resourceGroups/{rgName}/providers/Microsoft.Compute/virtualMachines/{name}/start

this is acceptable, but this

/subscriptions/{subsId}/resourceGroups/{rgName}/providers/Microsoft.Compute/virtualMachines/{vmName}/powerOff

is not acceptable.

Related swagger example

The changes in this PR https://github.com/Azure/azure-rest-api-specs/pull/20588 is aligning such a parameter name between two paths.

Category

SDK

Severity level

Error

Applies to

Management plane API spec, Data plane API spec

How to fix the violation

The swagger should rename the violated parameter name to keep them aligned with each other across different paths with parenting relationship

What't the impact if breaking the rule

This benefits the tools that validate parenting relationship between operations and resources, and will make the generated SDKs have aligned parameter names

jianyexi commented 2 years ago

So do we have suggestion on which name should be treated as the source of truth

tombuildsstuff commented 2 years ago

So do we have suggestion on which name should be treated as the source of truth

FWIW we're using the Resource itself (e.g. the VM) as the source of truth as other URIs are operations on this resource (e.g. /restart, or provisioning a nested resource under the parent resource) - so I'd suggest doing the same here such that given the URIs:

/subscriptions/{subsId}/resourceGroups/{rgName}/providers/Microsoft.Compute/virtualMachines/{name} /subscriptions/{subsId}/resourceGroups/{rgName}/providers/Microsoft.Compute/virtualMachines/{vmName}/restart /subscriptions/{subsId}/resourceGroups/{rgName}/providers/Microsoft.Compute/virtualMachines/{vmName}/extensions/{extensionName}

The URI /subscriptions/{subsId}/resourceGroups/{rgName}/providers/Microsoft.Compute/virtualMachines/{name} (and the segment name) should be the source of truth, and raise an error about these two operations:

/subscriptions/{subsId}/resourceGroups/{rgName}/providers/Microsoft.Compute/virtualMachines/{vmName}/restart /subscriptions/{subsId}/resourceGroups/{rgName}/providers/Microsoft.Compute/virtualMachines/{vmName}/extensions/{extensionName}

using the segment name vmName rather than name?