Swagger Generator Does Not Use All API Explorer Metadata

[commonsensesoftware]

Overview

The implementation of SwaggerGenerator.cs should consider all relevant metadata provided by API explorers. The following information is not currently mapped in all NonBodyParameter scenarios:

• Description - this can default to ApiParameterDescription.Documentation (also addresses Parameter Description Should Default to Parameter Descriptor Documentation #1101)
• Default - this can default to ApiParameterDescription.ParameterDescriptor.DefaultValue and must be set after the corresponding registered schema has been applied to prevent the value from being overwritten

In addition, the Consumes() and Produces() extension methods in ApiDescriptionExtensions.cs only use the MediaTypeValueHeader.MediaType value, which excludes additional information such as media type parameters. All media type information should be considered. This can easily be remedied using MediaTypeValueHeader.ToString().

These items were previously partially addressed by PR #1090, which is now closed and was never merged.

Scenarios

There are undoubtedly numerous scenarios where this would be useful. In the case of API Versioning, this will enable discovered API version parameters to be injected into Swagger documents and the UI via its API explorer extensions without requiring additional configuration from service authors. Service authors must currently use custom IOperationFilter implementations to bridge this gap.