Skip to content

Swagger LintDiff for TypeSpec

Jump to bottom
Mike Harder edited this page Jun 20, 2024 · 4 revisions

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".

Record<unknown> causes AvoidAdditionalProperties and PropertiesTypeObjectNoDefinition

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.

RequestBodyMustExistForPutPatch

We believe this is a false positive: https://github.com/Azure/azure-openapi-validator/issues/641

PatchPropertiesCorrespondToPutProperties

We believe this is a false positive: https://github.com/Azure/azure-openapi-validator/issues/642

@singleton causes EvenSegmentedPathForPutOperation and XmsPageableForListCalls

If EvenSegmentedPathForPutOperation and/or 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

AvoidAnonymousParameter, AvoidAnonymousTypes, IntegerTypeMustHaveFormat

Data-plane specs can suppress violations of the following rules, since they only exist 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 these rules, since resource-manager SDKs are generated from OpenAPI, and rely on these errors being fixed.

  • AvoidAnonymousParameter
  • AvoidAnonymousTypes
  • IntegerTypeMustHaveFormat

AvoidAnonymousTypes inside a 202 response

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.

OAuth2Auth causes XmsEnumValidation

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.

ProvisioningStateMustBeReadOnly

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.

ResourceNameRestriction

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.

PatchBodyParameterSchema

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.

Overview

TypeSpec

Engineering System

Meta

Under Construction

Clone this wiki locally