RicoSuter/NSwag

Using XML code documentation for generic types is not working

Open

#2,537 opened on Nov 21, 2019

View on GitHub
 (1 comment) (0 reactions) (0 assignees)C# (1,189 forks)batch import
help wanted

Repository metrics

Stars
 (6,291 stars)
PR merge metrics
 (No merged PRs in 30d)

Description

Here is my solution setup

Service1
  Service1Controller.cs //contains XmlDoc for methods
    public async Task<Result<SumResult>> Post([FromBody] SumRequest request)

Service1.Def
  SumRequest .cs //contains XmlDoc
  SumResult.cs //contains XmlDoc

ServiceResult
  ServiceResult.cs //contains XmlDoc

I've configured the middleware and here is the (abbreviated) result for the models:

{
  "ResultOfSumResult": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "success": {
        "type": "boolean"
      }
      /* other properties ommitted */
    }
  },
  "SumResult": {
    "type": "object",
    "description": "Describes the result of a sum",
    "additionalProperties": false,
    "properties": {
      "result": {
        "type": "integer",
        "description": "The result",
        "format": "int32"
      }
    }
  },
  "SumRequest": {
    "type": "object",
    "description": "Describes a sum",
    "additionalProperties": false,
    "properties": {
      "x": {
        "type": "integer",
        "description": "Left hand side of the sum",
        "format": "int32"
      },
      "y": {
        "type": "integer",
        "description": "Right hand side of the sum",
        "format": "int32"
      }
    }
  }
}

}

As you can see, ResultOfSumResult (which maps to Result) does not have description for the properties

There is a ServiceResult.xml file in the bin directory with at least the following:

    <member name="T:ServiceResult.Result`1">
        <summary>
        Describe the result of an operation
        </summary>
        <typeparam name="T"></typeparam>
    </member>
    <member name="P:ServiceResult.Result`1.Success">
        <summary>
        Was the operation successful ?
        </summary>
    </member>

I've also used a generic return type directly in the same assembly with same output, so I definitely think this is a problem with generic types.

I looked at #2161 and #1408 which I think are related but I did not find solution there

So my question is : will this be supported in NSwag ?

Contributor guide