RicoSuter/NSwag

Using XML code documentation for generic types is not working

開放

#2,537 建立於 2019年11月21日

 (1 則留言) (0 個反應) (0 位負責人)C# (1,357 個分叉)batch import
help wanted

倉庫指標

星標
 (7,359 顆星)
PR 合併指標
 (30 天內沒有已合併 PR)

描述

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 ?

貢獻者指南