Как включить описания классов и свойств в Swashbuckle сгенерированные документы Swagger для WebApi 2 с OWIN?

прежде чем вы подумаете об этом, этой - это не то же самое.

Я думаю, что это должно быть довольно много пояснений. Я хотел бы включить описания классов в документы Swagger. Мой Swagger config выглядит так:

config.EnableSwagger(c =>
{
    c.SingleApiVersion("v1", "My Api Name");
    c.OperationFilter<AddAuthorizationHeaderParameterOperationFilter>();
    c.IncludeXmlComments(GetXmlCommentsPath());

}).EnableSwaggerUi(c => { });

и MyAwesomeController выглядит так:

/// <summary>
/// Controller description (is included by Swashbuckle)
/// </summary>
public class MyAwesomeController : ApiController
{
    /// <summary>
    /// Method description (is included by Swashbuckle)
    /// </summary>
    public IHttpActionResult Get()
    {
        return Ok("hello... from the other side");
    }

    public IHttpActionResult Post([FromBody]MyAwesomeModel model)
    {
        return Ok("hello... from the other side");
    }
}

и меня MyAwesomeModel выглядит так:

/// <summary>
/// **I would like this to be included in the Swagger description of the parameter**
/// </summary>
public class MyAwesomeModel
{
    /// <summary>
    /// **I would like this to be included in the Swagger description of the parameter**
    /// </summary>
    public string MyProperty { get; set; }
}

возможно ли это без найма старшего скита?

6
asp.net-web-api owin swagger swashbuckle

2 ответов

тю... так что, возможно, если кто-то еще столкнется с этим.

в основном я нашел один способ сделать это, и я понял, почему это не было сделано по умолчанию. Не уверен, что это лучший подход, но вот он идет.

в моем решении POCOs расположены в проекте отдельно от фактического API и, таким образом, описание комментария MyAwesomeModel не был включен, поскольку для классов и свойств не были созданы узлы XML. Итак, в моем отдельном проекте, где POCOs были расположенный я изменил свойства для создания XML.

  1. создать XML для проекта, где POCOs расположены

Output XML for the project where model classes are located

  1. убедитесь, что XML скопирован на любой путь, который вы хотели бы Swashbuckle искать его. Я использовал Post-build event command line в свойствах проекта;

copy "$(SolutionDir)MyAwesomeProjectWithPocos\bin\MyAwesomeProjectWithPocos.xml" "$(ProjectDir)\bin\MyAwesomeProjectWithPocos.xml"

Post-build event to copy the XML file to the same bin folder as the API xml file

  1. изменить SwaggerConfig включить этот XML как ну!--17-->

то есть

config.EnableSwagger(c =>
{
    c.SingleApiVersion("v1", "My Api Name");
    c.OperationFilter<AddAuthorizationHeaderParameterOperationFilter>();
    c.IncludeXmlComments(GetXmlCommentsPath());
    c.IncludeXmlComments(GetXmlCommentsPathForModels());

}).EnableSwaggerUi(c => { });

теперь, на странице Swagger, если я переключусь с Model Schema to Model теперь я могу прочитать всю модель и описания свойств.

Click models to see model and property comments

естественно, нет необходимости копировать XML-файл, можно просто указать правильное расположение в шаге #3 GetXmlCommentsPathForModels()); но это был мой выбор.

15

Если вы поставили ниже заявление

c.IncludeXmlComments(GetXmlCommentsPath());

можете ли вы проверить, возвращает ли метод XML comment path путь xml-файла, в котором находится файл документации XML проекта?

0