dotnet / dotnet/AspNetCore.Docs

Add documentation to support code generator MSBuild

Open
#8,461 5 comments 0 reactions 0 assignees View on GitHub
area-mvc doc-enhancement Pri1 re-Safia
Dominant language
C#
Stars
13.1k
Forks
24.6k
Avg merge
1d 3h
Merged PRs (30d)
97

Description

## 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
- 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 #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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.