RicoSuter/NSwag

Set Swagger response description via xml docs or attribute

Open

#1,746 opened on Nov 16, 2018

View on GitHub
 (23 comments) (4 reactions) (0 assignees)C# (1,189 forks)batch import
help wantedtype: enhancement

Repository metrics

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

Description

Update by @RicoSuter: Documentation about how to specify the response descriptions with XML Docs.

I'm on a .NET Core 2.1 Web API project and trying to obtain a complete swagger documentation like Swagger PetStore Demo. I've enabled the XML comments on my project, by adding the <GenerateDocumentationFile> tag on the .csproj file:

<GenerateDocumentationFile>true</GenerateDocumentationFile>

I'm using this syntax on my controllers:

[Authorize]
[ApiVersion("1.0")]
[Produces("application/json")]
[SwaggerTag("Anomalies", Description = "Anomalies management.")]
public class AnomaliesController : BaseController
{
	/// <summary>
	/// Find anomaly by ID
	/// </summary>
	/// <param name="id">ID of the anomaly to return</param>
	/// <response code="200">Successful operation</response>
	/// <response code="400">Invalid ID supplied</response>
	/// <response code="404">Anomaly not found</response>
	[HttpGet("{id:long}")]
	[ProducesResponseType(typeof(api.Anomaly), (int)HttpStatusCode.OK)]
	[ProducesResponseType((int)HttpStatusCode.BadRequest)]
	[ProducesResponseType((int)HttpStatusCode.NotFound)]
	public async Task<ActionResult<api.Anomaly>> Get(long id)
	{
		return Mapper.Map<api.Anomaly>(await Mediator.Send(new GetAnomalyByIdQuery() { Id = id }));
	}
}

I also tried with SwaggerResponse attribute:

[SwaggerResponse(HttpStatusCode.OK, typeof(api.Anomaly), Description = "Successfull operation")]

but without any result.

This is what I get:

image

This is what I want, like in PetStore Demo (red circle are my missing values):

image

Contributor guide