name not always displayed in azureresourceschema

[tfitzmac]

When I use the command:
autorest -Modeler Swagger -CodeGenerator AzureResourceSchema

The markdown files do not always include the description of the name property for the resource type. Here is an example of a resource type that doesn't include the name description - CDN profile.

However, other resource types include the name description, such as storage account.

[tfitzmac]

@jhendrixMSFT - here is a request for an update to the AzureResourceSchema module.

[anthony-c-martin]

Markdown support was actually pulled out as part of the move to v3. Sounds like this is still needed!

[tfitzmac]

Yes, I generate the template reference docs with this module. I added a work around for the issue with the name not showing up for some resource types. It sounds like I should be cautious about updating my installed version.

[ifeoluwaokunoren]

@anthony-c-martin can you please help resolve this?
Thanks.

[tfitzmac]

The other question to consider is whether using the swagger files is still the best option now that the schema files are being kept up-to-date. One problem I have right now is that polymorphic objects are not generated correctly from the current module. So, we need to change the module for polymorphic objects, and it's made we wonder if it should be completely redeveloped.

@anthony-c-martin - do you have a recommendation about whether swagger or schemas would be easier to work with? Particularly with regards to handling polymorphic objects.

[anthony-c-martin]

@tfitzmac Support for polymorphism is much better now as we've had to make a few fixes for schema generation. Those fixes are only in v3 however, which conveniently doesn't support the doc generation.

For the question on swagger vs schemas, I think it depends on what you're doing with the documentation. If you're just describing APIs, then swagger for sure. If you're generating docs to show the template schema, then it probably makes more sense to keep it here and integrate with the latest changes - that way the docs & actual schemas would be more in sync, plus we're not reinventing things.