Add documentation to support code generator MSBuild

[dougbu]

General

dotnet/aspnetcore#4896 includes a number of extension points for code and document generator providers. We plan to submit example extensions to the https://github.com/RSutor/NSwag repo but not to do the same for (say) Swashbuckle or AutoRest. Owners of other generators will thus require documentation of how to work with the coming Microsoft.Extensions.ApiDescription.Client package.

Requests for new Topics

Topic will cover requirements for implementing BlahDocumentGenerator, BlahCSharpCodeGenerator and BlahTypeScriptCodeGenerator targets, how those targets will be invoked, and suggested package dependencies. See RicoSuter/NSwag#1587 for example; that issue covers creating a package containing NSwagCSharpCodeGenerator and NSwagTypeScriptCodeGenerator targets. (RicoSuter/NSwag#1588 covers implementing the BlahDocumentGenerator target but the pattern is identical.)

Contents

• Link to the https://docs.microsoft.com/en-ca/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-2.1 documentation, as updated in Describe new client code generation features (planned for 2.2 Preview 3) #8460
• Describe motivation for the work and benefits to code and document generator providers
• Describe the (minimal) MSBuild needed to wrap an existing code or document generator tool
• Describe any optional additions providers may choose to implement
• Link to NSwag samples implementing these enhancements

Placement

This documentation doesn't really belong in the "Building Web APIs" tutorial and it's not clear to me where those wishing to extend ASP.NET Core would look first. Perhaps we need a new "chapter" providing guidance for those extending the framework?

CC

@glennc

[Rick-Anderson]

@scottaddie is any of this completed?

[scottaddie]

@Rick-Anderson No. Looks like the engineering work is still in progress. I've updated Doug's description with the updated issue.

[dougbu]

@glennc given the low number of code generators, how important is this documentation for our partners i.e. is it really a P1?

[dougbu]

Reframed to more closely align with #8465

[dougbu]

Discussed offline w/ @glennc. This issue should be addressed for the benefit of the ecosystem, including partners who choose not to interact with Microsoft directly.