RicoSuter/NSwag

DescriptionAttribute on an operation method is parsed as a summary instead of a description

Open

#1,930 opened on Jan 28, 2019

View on GitHub
 (2 comments) (3 reactions) (0 assignees)C# (1,189 forks)batch import
help wanted

Repository metrics

Stars
 (6,291 stars)
PR merge metrics
 (No merged PRs in 30d)

Description

The content of a DescriptionAttribute on a controller method (operation) is parsed into a OpenAPI summary field instead of a description field. This seems to be a bug, and leads to incorrect displaying in frontends like ReDoc.

The issue is located in this piece of code:

            dynamic descriptionAttribute = context.MethodInfo.GetCustomAttributes()
                .SingleOrDefault(a => a.GetType().Name == "DescriptionAttribute");

            if (descriptionAttribute != null)
                context.OperationDescription.Operation.Summary = descriptionAttribute.Description;
            else
            {
                var summary = await context.MethodInfo.GetXmlSummaryAsync().ConfigureAwait(false);
                if (summary != string.Empty)
                    context.OperationDescription.Operation.Summary = summary;
            }

(https://github.com/RSuter/NSwag/blob/master/src/NSwag.SwaggerGeneration/Processors/OperationSummaryAndDescriptionProcessor.cs)

As seen, the Operation.Summary field is set instead of Operation.Description as expected.

The documentation seems correct, as it says:

DescriptionAttribute on the action method (used as Swagger operation 'Description')

(https://github.com/RSuter/NSwag/wiki/WebApiToSwaggerGenerator#supported-aspnet-web-api-attributes)

I noticed that this issue was previously mentioned in a comment on another issue, but likely since forgotten: https://github.com/RSuter/NSwag/issues/292#issuecomment-246939878

Contributor guide