[Documentation] Guidance for AutoRest config README contents

[mikekistler]

Many parts of our process depend on the readme.md file for a service in azure-rest-api-specs, but I am not aware of any documentation on the required structure or content of this file. When the "avocado" check for a PR fails because of incorrect readme content or structure, service teams are left to guess what should be done fix.

We need to clearly document the required structure and contents of readme.md and put this in an easily discoverable location.

cc: @ccbarragan @josefree @konrad-jamrozik

[maririos]

@mikekistler is this what you are looking for? https://eng.ms/docs/products/azure-developer-experience/design/api-specs/api-autorest

[mikekistler]

That looks promising but is missing important information, like how tagging works and how tagged releases should be structured. Avocado errors like MULTIPLE_API_VERSION and MISSING_APIS_IN_DEFAULT_TAG don't make any sense to service teams if they don't understand how tags work and are expected to be structured.

[maririos]

Who has that context to update the doc? @konrad-jamrozik is this you?

[konrad-jamrozik]

@mikekistler @maririos we have this work item:

• https://github.com/Azure/azure-sdk-tools/issues/6886 Which points out this article needs to be migrated:
• https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/80/Getting-started-with-OpenAPI-specifications

(which is duplicated-and-partially-outdated here)

Which links to this:

• https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/creating-swagger.md

But honestly I don't think I should take care of migrating it. This is about spec contents authoring and my area of responsibility is supporting the tooling for validating the specs, not the specs contents and conventions.

Relevant note: Swagger Avocado is no longer a required check to merge any specs PRs.

@weshaggard FYI