Before you think of it, this is not the same.
I think this should be pretty much self explanatory. I would like to include class descriptions in the Swagger docs. My Swagger
config looks like this:
config.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "My Api Name");
c.OperationFilter<AddAuthorizationHeaderParameterOperationFilter>();
c.IncludeXmlComments(GetXmlCommentsPath());
}).EnableSwaggerUi(c => { });
And MyAwesomeController
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 my MyAwesomeModel
looks 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?
Hm... so maybe if someone else runs into this.
Basically I found one way this can be done and I realized why it was not done by default. Not sure if it is the best approach but here it goes.
In my solution, the POCOs are located in a project separate to the actual API and thus, the comment description of MyAwesomeModel
was not included because no XML nodes were generated for the classes and properties. So, in my separate project where the POCOs were located I modified properties to generate an XML.
Swashbuckle
to look for it. I used Post-build event command line
in project properties;copy "$(SolutionDir)MyAwesomeProjectWithPocos\bin\MyAwesomeProjectWithPocos.xml" "$(ProjectDir)\bin\MyAwesomeProjectWithPocos.xml"
SwaggerConfig
to include this XML as wellI.e.
config.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "My Api Name");
c.OperationFilter<AddAuthorizationHeaderParameterOperationFilter>();
c.IncludeXmlComments(GetXmlCommentsPath());
c.IncludeXmlComments(GetXmlCommentsPathForModels());
}).EnableSwaggerUi(c => { });
Now, on the Swagger page, if I switch from Model Schema
to Model
I can now read the entire model and property descriptions.
Naturally, there is no demand to copy the XML file, one may just point to the correct location in step #3 GetXmlCommentsPathForModels());
but this was my option.