Azure / typespec-azure

About TypeSpec Azure Libraries
https://azure.github.io/typespec-azure/
MIT License
11 stars 36 forks source link

Add a linter rule to discourage using @useRef decorator #1195

Closed MaryGao closed 1 week ago

MaryGao commented 1 month ago

In typespec service team could use @useRef to generate new swagger similar to their old swagger(if in that swagger they have some references).

Here is an example from Azure Fleet, if we try to generate SDK from typespec directly we will get an empty model for ApiError the referenced swagger definition would only work for OpenAPI emitter. In that case we should report this out to ask service team to migrate referenced swagger to typespec also.

Once the service team finish their migration there is no need to refer any swagger definition. So it's better to have a linter rule to warn the usage for @useRef out.

tsp definition

@doc("ApiError for Fleet")
@useRef("../../../../../compute/resource-manager/Microsoft.Compute/common-types/v1/common.json#/definitions/ApiError")
model ApiError {}

generated swagger

"error": {
    "$ref": "../../../../../compute/resource-manager/Microsoft.Compute/common-types/v1/common.json#/definitions/ApiError",
    "description": "Error Information when `operationStatus` is `Failed`",
    "readOnly": true
  }
timotheeguerin commented 1 month ago

Agreed, I think though this should just be a rule to say do not use anything from autorest library(and openapi)

markcowl commented 1 month ago

est: 3