我正在编写一个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来描述下载方法。我对要使用的正确属性有些困惑-摇晃响应还是产生响应类型?我应该同时使用吗?为什么我偏爱一个?
感谢您提前提出任何建议! :)