-
Notifications
You must be signed in to change notification settings - Fork 5.1k
Swagger LintDiff for TypeSpec
Check Swagger LintDiff may fail for the OpenAPI generated from TypeSpec, even if there are no warnings or errors reported from the TypeSpec compiler. Causes include bugs in the TypeSpec OpenAPI emitter, bugs in LintDiff rules, incompatibilities between TypeSpec and LintDiff, or checks duplicated in TypeSpec and LintDiff.
We are working to address the root causes (where possible). Until then, we recommend you suppress these LintDiff errors, using a "permanent suppression" with a descriptive "reason".
The use of Record<unknown> in TypeSpec is discouraged, and there is a TypeSpec lint rule to enforce this. If you still need to use Record<unknown>, the OpenAPI spec generated will cause many LintDiff errors of types AvoidAdditionalProperties and PropertiesTypeObjectNoDefinition. You will need to suppress both the TypeSpec violation (in TypeSpec source code) and the LintDiff violations.
Data-plane specs can suppress violations of this rule, since it only exists for the benefit of SDKs generated from swagger, and data-plane SDKs are generated directly from TypeSpec. Resource-manager specs should not suppress violations of this rule, since resource-manager SDKs are generated from OpenAPI, and rely on these errors being fixed.
As an exception to the previous note, resource-manager specs may be able to suppress AvoidAnonymousTypes, but only if the error is inside a 202 response from a long-running operation (LRO). It is known that SDKs do not need to generate type names for such responses.
Data-plane specs can suppress violations of this rule, since it only exists for the benefit of SDKs generated from swagger, and data-plane SDKs are generated directly from TypeSpec. Resource-manager specs should not suppress violations of this rule, since resource-manager SDKs are generated from OpenAPI, and rely on these errors being fixed.
If EvenSegmentedPathForPutOperation is failing for OpenAPI generated from TypeSpec using @singleton (OpenAPI path ends with /default), we believe this is a false positive: https://github.com/Azure/azure-openapi-validator/issues/646
Data-plane specs can suppress violations of this rule, since it only exists for the benefit of SDKs generated from swagger, and data-plane SDKs are generated directly from TypeSpec. Resource-manager specs should not suppress violations of this rule, since resource-manager SDKs are generated from OpenAPI, and rely on these errors being fixed.
The root cause is a bug in typespec-azure:
https://github.com/Azure/typespec-azure/issues/383.
Please see the issue above for the suggested workaround and apply it directly to the spec TypeSpec sources. The LintDiff error should not be ignored or suppressed.
We believe this is a false positive: https://github.com/Azure/azure-openapi-validator/issues/642
The use of Record<unknown> in TypeSpec is discouraged, and there is a TypeSpec lint rule to enforce this. If you still need to use Record<unknown>, the OpenAPI spec generated will cause many LintDiff errors of types AvoidAdditionalProperties and PropertiesTypeObjectNoDefinition. You will need to suppress both the TypeSpec violation (in TypeSpec source code) and the LintDiff violations.
The root cause is bugs in azure-openapi-validator and oav:
https://github.com/Azure/azure-openapi-validator/issues/637 https://github.com/Azure/oav/issues/848
The recommended workaround is to add use-read-only-status-schema: true to your tspconfig.yaml.
We believe this is a false positive: https://github.com/Azure/azure-openapi-validator/issues/641
Whether ResourceNameRestriction should be applied to enums is an open question:
https://github.com/Azure/azure-openapi-validator/issues/501 https://github.com/Azure/azure-openapi-validator/pull/714
Until this is resolved, suppress the errors and discuss with your ARM reviewer.
TypeSpec using OAuth2Auth may generate the following OpenAPI:
"type": {
"type": "string",
"description": "OAuth2 authentication",
"enum": [
"oauth2"
]
},Which causes error XmsEnumValidation. The recommended workaround is to add omit-unreachable-types: true to your tspconfig.yaml.
If XmsPageableForListCalls are failing for OpenAPI generated from TypeSpec using @singleton (OpenAPI path ends with /default), we believe this is a false positive: https://github.com/Azure/azure-openapi-validator/issues/646