ASP.net Core Web API-正确的标点符号

我正在编写一个Web API,并用各种GET,POST方法等定义了一个控制器。我在文档中使用Swagger Open API,并且想了解正确的注释方法。这是我拥有的控制器方法的示例:

/// <summary>Download a file based on its Id.</summary>
/// <param name="id">Identity of file to download.</param>
/// <returns><see cref="MyFile" /> file content found.</returns>
[HttpGet("download/{id}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[SwaggerResponse(200, "Myfile content", typeof(MyFile))]
[SwaggerResponse(404, "Could not find file", typeof(MyFile))]
public async Task<IActionResult> DownloadAsync(int id)
{
    const string mimeType = "application/octet-stream";
    var myFile = await _dbContext.MyFiles.FindAsync(id);

    // If we cannot find the mapping, return 404.
    if (myFile.IsNullOrDefault())
    {
        return NotFound();
    }

    // Download using file stream.
    var downloadStream = await _blobStorage.DownloadBlob(myFile.FileLocation);
    return new FileStreamResult(downloadStream, mimeType) { FileDownloadName = myFile.FileName };
}

如您所见,我同时使用ProducesResponseType和SwaggerResponse来描述下载方法。我对要使用的正确属性有些困惑-摇晃响应还是产生响应类型?我应该同时使用吗?为什么我偏爱一个?

感谢您提前提出任何建议! :)

评论