asp.net-core – 在Swagger中使用属性XML注释作为参数描述

2019年7月28日 512次阅读

我使用ASP.NET Core创建了一个Web API,并使用swagger来创建文档.我在API端点上使用
XML注释来提供文档中的其他信息.招摇的配置是：

services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });

            // Set the comments path for the Swagger JSON and UI.
            var basePath = AppContext.BaseDirectory;
            var xmlPath = Path.Combine(basePath, "MyAPI.xml");
            c.IncludeXmlComments(xmlPath);
        });

我的一个API端点及其XML注释是：

    /// <summary>
    /// Find an existing appointment using the visitor information: First name, last name, email, phone.
    /// </summary>
    /// <url>http://apiurl/api/appointments/appointmentsByVisitor</url>
    /// <param name="criteria">consists of one or more of:  Firstname, lastname, email, phone</param>
    /// <returns>Existing appointment data in an Appointment object or a business error.</returns>
    /// <response code="200">Returns the existing appointment event.</response>
    /// <response code="400">Returns if no parameters are specified.</response>            
    /// <response code="204">Returns if there's no matching appointment.</response>
    /// <response code="500">Returns if there's an unhandled exception.</response>
    [Authorize]
    [HttpGet("appointmentsByVisitor")]
    [ProducesResponseType(typeof(Appointment), 200)]
    [ProducesResponseType(typeof(BusinessError), 404)]
    public IActionResult AppointmentsByVisitor([FromQuery] VisitorSearchCriteria criteria) {}

VisitorSearchCriteria是一个单独的类,它是API端点所期望的参数的包装器.

public class VisitorSearchCriteria
{
    /// <summary>
    /// Visitor first name.
    /// </summary>
    public string FirstName { get; set; }

    /// <summary>
    /// Visitor last name.
    /// </summary>
    public string LastName { get; set; }

    // several other properties....
}

此API端点的swagger文档将VisitorSearchCriteria的所有属性显示为参数,但它不会选择XML注释.请参见下面的截图.

《asp.net-core – 在Swagger中使用属性XML注释作为参数描述》

如您所见,缺少参数的描述.如何告诉swagger使用该外部类的XML注释来创建参数描述？

最佳答案
http://wmpratt.com/swagger-and-asp-net-web-api-part-1/

First, enable XML documentation file creation during build. In
Solution Explorer right-click on the Web API project and click
Properties. Click the Build tab and navigate to Output. Make sure XML
documentation file is checked. You can leave the default file path. In
my case its bin\SwaggerDemoApi.XML

点赞