search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.63k stars 25.29k forks source link

Add documentation to support code generator MSBuild #8461

Open dougbu opened 6 years ago

dougbu commented 6 years ago

General

https://github.com/aspnet/AspNetCore/issues/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 RSuter/NSwag#1587 for example; that issue covers creating a package containing NSwagCSharpCodeGenerator and NSwagTypeScriptCodeGenerator targets. (RSuter/NSwag#1588 covers implementing the BlahDocumentGenerator target but the pattern is identical.)

Contents

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 commented 5 years ago

@scottaddie is any of this completed?

scottaddie commented 5 years ago

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

dougbu commented 5 years ago

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

dougbu commented 5 years ago

Reframed to more closely align with #8465

dougbu commented 5 years ago

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.