Swashbuckle.aspnetcore: 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:

• Required - this can be determined by location and by ApiParameterDescription.RouteInfo.IsOptional
• Description - this can be determined by ApiParameterDescription.ModelMetadata.Description, when available
• Default - this can be determined by ApiParameterDescription.RouteInfo.DefaultValue

Scenarios

There are undoubtedly numerous scenarios where this woudl 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.

[steveoh]

It seems the microsoft docs think the [Required] and [DefaultValue(true)] work with this. I'm noticing that they do not.

Maybe I am doing something wrong but I do not see default: anywhere in the json.

• I EnableAnnotations() in the SwaggerGen to no affect.
• I added the new annotations lib thinking that might help but it did not affect the output.

[commonsensesoftware]

This thread has gone quiet, but it's not dead. @domaindrivendev and I have talked it over. Ultimately, this is being held up by https://github.com/aspnet/Mvc/issues/7563, which demonstrates a gap in the API Explorer library. It has been updated, but not published. Once that happens, this thread can breathe new life.

[CumpsD]

It seems it happened: https://github.com/Microsoft/aspnet-api-versioning/issues/414

[commonsensesoftware]

Indeed this has happened in both the ASP.NET Core and API Versioning libraries. It does, however, require ASP.NET Core 2.2+.

@domaindrivendev, I tried reaching out by email before the holidays. Perhaps you've been busy, away, or my message fell into the _Inbox Abyss_. Regardless, we should rehash and discuss how this information should manifest in a Swagger document now that it's possible.

Once the details are hashed out about how this information _should_ be used, I think a new PR can be created to close this out whether that's by me or some other eager community member. :)

[bartlannoeye]

What's the state of this issue?

[lonix1]

Do we need to use the SwaggerDefaultValues class until this issue is closed?

[commonsensesoftware]

You don't _have_ to. This class is providing bridge to fill in default values from the API Explorer. If you don't need that, things will work just fine.

In addition to Required, Description, and DefaultValue, it was recently brought to my attention that there is also a gap with respect to Deprecated. This is not specific to the API Explorer though as it does not provide this information. However, I do think it's worth discussing, even if it means creating a new issue, that a new hook (ex: callback) that can bridge the deprecated information from API Versioning to Swashbuckle would be useful. The most current version of SwaggerDefautlValues shows how to do this, but would not currently be addressed by this issue.

This issue may be moving slow due to the priority of other issues, but it's not forgotten. Keep pushing for it. It's going to happen - eventually. ;)

[jstawski]

Any news on this? I'm trying to write a DocumentFilter that defaults the version parameter automatically using DefaultValue and it doesn't seem to be working:

public class VersionDefaultingDocumentFilter : IDocumentFilter
{
    public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
    {
        var version = swaggerDoc.Info.Version.Replace("v", "");
        foreach(var ad in context.ApiDescriptions)
        {
            var versionParam = ad.ParameterDescriptions.Where(pd => pd.Name == "version").FirstOrDefault();
            if (versionParam != null)
                versionParam.DefaultValue = version;
        }
    }
}

[RehanSaeed]

@commonsensesoftware The Versioning sample has a SwaggerDefaultValues IOperationFilter that references this issue.

Now that ASP.NET Core 3.0 is out, can this be resolved?

[commonsensesoftware]

@RehanSaeed does Swashbuckle support or otherwise use all of the relevant, provided metadata now? I was under the impression the answer is still no. If it does, then this issue could be resolved. The gap with respect to deprecation is interesting, but it's not based on metadata so that can be a new issue.

[ericsampson]

@commonsensesoftware is this fixable now? I have trouble tracking all the moving pieces across the various parts of the stack here, sorry :D I'd be happy to help if someone can point out what needs to be done now.

[commonsensesoftware]

@ericsampson it is _fixable_. There was a time when IsOptional was the wrong thing (it meant something different). There is now a IsRequired property on API descriptors. There is also a DefaultValue. These just aren't being consumed. There are two other issues that have cropped up as well. There is no _good_ way to hook API Versioning to Swashbuckle for _deprecated_ APIs. Swashbuckle would need to provide a _hook_ to connect the two. API Versioning has a way to report this, but there's no way to marry the two without a filter. Additionally, a few people have mentioned that when versioning by media type, Swashbuckle does not honor the reported values. I was able to confirm that. The values appear to be hardcoded or somehow otherwise assumed. For example, when the reported media type should be application/json; v=2.0, Swashbuckle still reports application/json. Updating the values in a filter will force Swashbuckle to do the _right_ thing.