Я создал веб-API с помощью ASP.NET Core и использовал чванство для создания документации. Я использую XML-комментарии к своим конечным точкам API, чтобы предоставить дополнительную информацию в документации. Конфигурация чванства:
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....
}
Документация swagger для этой конечной точки API показывает все свойства VisitorSearchCriteria как параметры, но не выбирает комментарии XML. Смотрите скриншот ниже.
Как видите, описания параметров отсутствуют. Как мне сказать Swagger использовать XML-комментарии из этого внешнего класса для создания описаний параметров?
