search

RicoSuter / NSwag

The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript.
http://NSwag.org
MIT License
6.78k stars 1.29k forks source link

Using both ProducesResponseType and SwaggerResponse produces an "or" in the documentation #946

Open fleed opened 7 years ago

fleed commented 7 years ago

Specifying both ProducesResponseType and SwaggerResponse attributes creates a documentation with an or between the SwaggerResponse.Description property and the value of the returns documentation of the method (response 200).

For all other responses, the output is an or between the SwaggerResponse.Description and empty string (the .NET attribute doesn't support a description https://docs.microsoft.com/en-us/aspnet/core/api/microsoft.aspnetcore.mvc.producesresponsetypeattribute#Properties)

RicoSuter commented 7 years ago

So the idea is to ignore empty descriptions for the "or"ed description?

fleed commented 7 years ago

@RSuter actually I would prefer to show only the content of the SwaggerResponse.Description attribute. The <returns></returns> value should be used for status code 200 only as fallback if the SwaggerResponse(200) attribute is not specified.

RicoSuter commented 7 years ago

I dont see the problem (see commit)

zuckerthoben commented 7 years ago

Having both ProducesResponseType and SwaggerResponse in your code looks like an unfinished refactoring. I am not sure that NSwag should work around a bad implementation.

RicoSuter commented 7 years ago

Currently, ProducesResponesTypeAttribute and SwaggerResponseAttribute are treated as if they were the same. Maybe we should process ProducesResponesTypeAttribute only if no SwaggerResponseAttributes are defined?

Respecting this rule: https://github.com/RSuter/NSwag/pull/994#discussion_r144952082