Documentation is not generated for routes with generic parameters or return types.
See original GitHub issueIn our organization, we have generic abstract controllers that we use as base controllers for all our data access APIs. The current algorithm that swagger uses to generate the documentation doesn’t know how to handle this scenario because the method documentation signature has generic heuristics.
Here is an example of what the controller looks like with one of the generic methods included.
public abstract class ReadController<TEntity, TKey, TContext, TFilter, TInclude> :
ApiController
where TEntity : class, new()
where TContext : IDbContext
where TFilter : class, new()
where TInclude : struct, IComparable, IConvertible, IFormattable
{
/// <summary>
/// Gets the entity by the given key.
/// </summary>
[Route("{key}")]
[HttpGet]
public virtual async Task<HttpResponseMessage> Get(TKey key, [FromUri] ICollection<TInclude?> includes = null, [FromUri] ICollection<string> fields = null)
{
}
}
The XML that is generated for this method output by MSbuild is as follows:
<member name="M:Jane.Data.WebHost.ReadController`5.Get(`1,System.Collections.Generic.ICollection{System.Nullable{`4}},System.Collections.Generic.ICollection{System.String})">
<summary>
Gets the entity by the given key.
</summary>
</member>
Even though we are including this XML
file in the bin folder and ensure it gets added through the swagger call IncludeXmlComments()
, no documentation is added to the route in the SwaggerUI.
The issue lies in the ApplyXmlActionComments.Apply()
method in Swashbuckle.Swagger
; essentially, it just fails to comprehend this method signature in the XML file and therefore cannot match the generic method to its documentation.
Would be nice to have this scenario accounted for so as to make generic routes display documentation as desired.
Issue Analytics
- State:
- Created 7 years ago
- Comments:46 (22 by maintainers)
Top GitHub Comments
I have the same issue!
@yojagad Done the update version is on nuget.org: https://www.nuget.org/packages/Swagger-Net/8.3.3.103