Azure / typespec-azure

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

feat(tcgc): use `@server` description for default `endpoint` client parameter #1007

Closed archerzz closed 1 week ago

archerzz commented 1 month ago

Clear and concise description of the problem

This is a minor issue.

See cadl-ranch server definition: https://github.com/Azure/cadl-ranch/blob/2fb006d5b4609647138382bf5d248a2edbde7742/packages/cadl-ranch-expect/src/decorators.ts#L241 There is no parameter defined for endpoint, instead it's a hard-coded value.

context.call($server, target, "http://localhost:3000", "TestServer endpoint");

TCGC will give a default endpoint parameter with description Service host. Maybe we should use the description defined in @server? e.g. for this case, it's TestServer endpoint.

Checklist

archerzz commented 3 weeks ago

Maybe we should differentiate a constant endpoint URL case from an expression endpoint URL case. For endpoint which is an expression, it would be better that each template argument description is undefined? (it doesn't make sense to assign service description to them)

@server(
    "{firstTestTypeSpecUrl}",
    "Endpoint Service",
    {
        firstTestTypeSpecUrl: string,
    }
)
archerzz commented 3 weeks ago

Another example of why we might need to leave uri template parameter as-is: image

archerzz commented 1 week ago

We have further discussion, and we thought it might be better to just leave description empty if it's not defined. And let each language emitter to decide what they want to add.