RicoSuter/NSwag

Set Swagger response description via xml docs or attribute

Open

#1,746 建立於 2018年11月16日

在 GitHub 查看
 (23 留言) (4 反應) (0 負責人)C# (1,189 fork)batch import
help wantedtype: enhancement

倉庫指標

Star
 (6,291 star)
PR 合併指標
 (30 天內沒有已合併 PR)

描述

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

貢獻者指南