Как включить описания классов и свойств в 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; }
}
возможно ли это без найма старшего скита?
2 ответов
тю... так что, возможно, если кто-то еще столкнется с этим.
в основном я нашел один способ сделать это, и я понял, почему это не было сделано по умолчанию. Не уверен, что это лучший подход, но вот он идет.
в моем решении POCOs расположены в проекте отдельно от фактического API и, таким образом, описание комментария MyAwesomeModel
не был включен, поскольку для классов и свойств не были созданы узлы XML. Итак, в моем отдельном проекте, где POCOs были расположенный я изменил свойства для создания XML.
- создать XML для проекта, где POCOs расположены
- убедитесь, что XML скопирован на любой путь, который вы хотели бы
Swashbuckle
искать его. Я использовалPost-build event command line
в свойствах проекта;
copy "$(SolutionDir)MyAwesomeProjectWithPocos\bin\MyAwesomeProjectWithPocos.xml" "$(ProjectDir)\bin\MyAwesomeProjectWithPocos.xml"
- изменить
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
теперь я могу прочитать всю модель и описания свойств.
естественно, нет необходимости копировать XML-файл, можно просто указать правильное расположение в шаге #3 GetXmlCommentsPathForModels());
но это был мой выбор.
Если вы поставили ниже заявление
c.IncludeXmlComments(GetXmlCommentsPath());
можете ли вы проверить, возвращает ли метод XML comment path путь xml-файла, в котором находится файл документации XML проекта?