Add documentation for API description providers in web sites

[dougbu]

General

#4896 includes (and the Microsoft.Extensions.ApiDescription.Client package will include) a generic tool that retrieves API descriptions from web sites. Though the tool can fire up the web site (in TestServer) and download the description from a URI, that requires site-specific configuration. The tool first attempts to get a service from DI and call a method on that service to get the API description. This issue is about documenting that service for providers (such as NSwag and Swagger) with packages extending web sites to generate API descriptions.

We plan to submit an example service implementation to the https://github.com/RSutor/NSwag repo but not to do the same for (say) Swashbuckle. Further, that example will not (cannot) cover the various options providers have w.r.t. the service name, method name, or method signature. Other providers will thus require documentation of how to work with the new tool.

Requests for new Topics

Topic will cover requirements for implementing an Microsoft.Extensions.ApiDescriptions.IDocumentProvider service and how that service will be invoked. (Note: IDocumentProvider is just a name the service uses to activate the service. We won't include a definition of the interface in any Microsoft package. Providers may choose from a number of method signatures and, therefore, concrete interfaces.)

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 API description providers
• Describe the new tool's overall operation
• Describe the new service and implementation options
• Link to NSwag samples implementing these enhancements

Placement

Should probably go close to the documentation added in #8461

CC

@glennc

[dougbu]

@glennc given the low number of OpenAPI document providers, how important is this documentation for our partners i.e. is it really a P1 (@scottaddie's suggestion) or P2 (@danroth27's suggestion)?

[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.

[mkArtakMSFT]

This will be a good 5.0 issue.