Readme title and description does not talk about the service in auto generated mgmt plane packages

[ramya-rao-a]

Taking Azure Compute as an example, the auto generated ARM package has the below title in the generated readme

Azure ComputeManagementClient SDK for JavaScript

And the below 1 line description

This package contains an isomorphic SDK for ComputeManagementClient.

For someone landing on this readme either in this repo or on npm, there is no indication as to what this package is used for.

Can we extract these two lines from the readme file with metadata that accompanies the swagger files used to generate these packages? This way the service owners can add the relevant details?

At the very least

• The h1 should denote the service name
• The description that follows should call out some common use cases
• The description should have a link to the service docs

If the code generator supports extracting the above, then the mgmt plane team can look into adding the details to all the services.

cc @diberry who shared the feedback initially cc @sarangan12, @deyaaeldeen for thoughts on the code generator side cc @qiaozha for thoughts on the mgmt plane side

[qiaozha]

Actually. I have the same issues in Azure CLI generation.

Currently, there seems no probably information in the swagger that we can directly use for an overall description of what that service is about. https://github.com/Azure/azure-rest-api-specs/blob/master/specification/compute/resource-manager/Microsoft.Compute/stable/2021-03-01/cloudService.json#L5 There's is a description in here, but 1. not all the service had this description. 2. most RPs don't take this description seriously, it's inappropriate to use.

@nickzhums @lirenhe Do you think we should require service team to put a brief, valid, meaningful description for their service in swagger ?

About the link to their document. I totally agree. Just worried that there's no such mapping rule from doc to rp name in specification folder?

[ramya-rao-a]

Do you think we should require service team to put a brief, valid, meaningful description for their service in swagger ?

Yes. I believe moving to Track 2 can be an opportunity to require the service teams to provide meaningful data in the swagger.

I have started offline discussions on this and will update this thread once we have a confirmation

[ramya-rao-a]

@sarangan12 I moved this issue from the azure-sdk-for-js repo. This is a language agnostic problem and is worth discussing in the auto rest crew with other language teams

[sarangan12]

I will discuss with the crew and update this issue

[ramya-rao-a]

Recommendation from @joheredi in #703

Currently Client and ClientContext files are generated in the following form {Name} and {Name}Context we should include Client in the suffix so that the name of the library doesn't have to contain the word Client {Name}Client and {Name}ClientContext

[ramya-rao-a]

@qiaozha Assigning this to you as this is mainly needed for the mgmt plane packages