Swashbuckle.aspnetcore: [SwaggerResponse] Description does not show up.

[VictorioBerra]

Code:

        /// <summary>
        /// Gets all products.
        /// </summary>
        /// <param name="dataTableRequest">The requested product identifier.</param>
        /// <param>A jQuery DataTable server-side processing request. https://datatables.net/manual/server-side </param>
        /// <returns>All products.</returns>
        [HttpPost("DataTable", Name = ProductControllerRoute.GetProductPage)]
        [SwaggerResponse(StatusCodes.Status200OK, Description = "Existing products were successfully retrieved.")]
        public DataTableResponseViewModel<ProductViewModel> GetDataTable([FromBody]DataTablesAjaxPostViewModel dataTableRequest)
        => _productApplicationService.GetDataTable(dataTableRequest);

UI:

I have enabled XML comments, if that matters.

[VictorioBerra]

Also, [SwaggerTag] does nothing. I put it over my Products controller and cant find the text anywhere on the UI.

[domaindrivendev]

Have you explicitly enabled Annotations (now an add-on package) as described in the readme?

[domaindrivendev]

Seeing as you're already using XML comments for the operation and parameter descriptions, you should consider ditching the SwaggerResponse annotation and using XML comments for the response description too:

/// <summary>
/// Gets all products.
/// </summary>
/// <param name="dataTableRequest">The requested product identifier.</param>
/// <param>A jQuery DataTable server-side processing request. https://datatables.net/manual/server-side </param>
/// <response code="200">Existing products were successfully retrieved</response>
/// <returns>All products.</returns>
[HttpPost("DataTable", Name = ProductControllerRoute.GetProductPage)]
public DataTableResponseViewModel<ProductViewModel> GetDataTable([FromBody]DataTablesAjaxPostViewModel dataTableRequest)

[VictorioBerra]

Which is preferred? Is there benefits to going full in on one vs the other?

On Mon, Jul 16, 2018, 9:14 PM Richard Morris [e-mail]
wrote:

Seeing as you're already using XML comments for the operation and
parameter descriptions, you should consider ditching the SwaggerResponse
annotation and using XML comments for the response description too:

///

/// Gets all products.///

/// The requested product identifier./// A jQuery DataTable server-side processing request. https://datatables.net/manual/server-side /// Existing products were successfully retrieved/// All products.
[HttpPost("DataTable", Name = ProductControllerRoute.GetProductPage)]public DataTableResponseViewModel GetDataTable([FromBody]DataTablesAjaxPostViewModel dataTableRequest)

—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/816#issuecomment-405437330,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ACzG6x7Nyr9fMfI8inpE1Tf88J_yf3Tmks5uHUiVgaJpZM4VR8VG
.

[domaindrivendev]

It depends. All-in on XML comments is probably the current “de facto” as it’s a little cleaner looking, particularly when you start using multi-line, paragraphs etc. However, you still need to combine with ASP.NET Core’s ProducesResponseType attributes when you want to document additional status codes.

Also, some people prefer to reserve xml comments for code authors (intended audience) as opposed to API consumers. This would be another reason to use the Swagger specific annotations

So, it’s up to you

[VictorioBerra]

Thanks a lot.

[VictorioBerra]

Also I feel like there's additional vendor lock-in with the swagger attributes as well.

[domaindrivendev]

Agreed