How to include class and property descriptions in Swashbuckle generated Swagger documents for WebApi 2 with OWIN?

Before you think about it, this one doesn't match.

I think this should be pretty much self-evident. I would like to include class descriptions in Swagger docs. My configurator Swaggerlooks like this:

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

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

And MyAwesomeControllerit looks like this:

/// <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");
    }
}

And mine MyAwesomeModellooks like this:

/// <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; }
}

Is this possible without hiring Sr. Skeet?

+4
source share
2 answers

Hm ... it could be if someone else comes across this.

, , , . , , .

POCOs , API, MyAwesomeModel , XML. , , POCOs, XML.

  • XML , POCOs

Output XML for the project where the 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 XML API file

  1. SwaggerConfig, XML,

..

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

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

, Swagger, Model Schema Model, .

Click models to see comments on the model and properties.

, XML , # 3 GetXmlCommentsPathForModels());, .

+13

c.IncludeXmlComments(GetXmlCommentsPath());

, xml xml, XML ?

0

Source: https://habr.com/ru/post/1655084/


All Articles