私は Swagger を使用して自分のREST API(asp.net web api 2を使用)をドキュメント化しています。特定のapi呼び出しですか?次のようなxmlコメントを使用して、ステータスコード応答に注釈を付けています。
/// <summary>
/// Save a person
/// </summary>
/// <response code="200">Ok</response>
/// <response code="400">Bad Request</response>
/// <response code="500">Internal Server error</response>
public HttpResponseMessage SavePerson() {...}
このようなXMLコメントでcref = "TYPE HERE"を使用してみてください。
/// <response code="400" cref="CustomErrorModel">Bad Request</response>
しかし、Swaggerが提供する注釈を使用することをお勧めします。
[SwaggerResponse(HttpStatusCode.OK, Type = typeof(OnlineMerchantQueryResponseInformation))]
これでコントローラーを属性付けします。
署名は、データモデルではなくHttpResponseMessageを返すことを示しています。 IActionResultを返し、ASP.NET Coreを使用している場合は、 "ProducesResponseType"属性を使用できます。
[ProducesResponseType(typeof(IEnumerable<YourModel>), 200)]
ProducesResponsesTypeは、Microsoft.AspNetCore.Mvc名前空間にあります。
参照 https://github.com/domaindrivendev/Swashbuckle.AspNetCore#list-operation-responses "Explicit Responses"
Swashbuckleを使用している場合は、
[SwaggerResponse(200, typeof(CustomModel))]
さらに、その応答タイプのコメントをオプションの3番目のパラメーターとして追加します
[SwaggerResponse(200, typeof(CustomModel), "returns a new id of the bla bla")]
注:属性は名前空間にありますSwashbuckle.AspNetCore.Annotations