title: ASP.net Core Web API - correct swagger annotations
body: <p>I am writing a Web API and have defined a controller with various GET, POST methods etc.  I am using Swagger Open API for my documentation and want to understand the correct way to annotate.  Here's an example of a controller method I have:</p>
  
  <pre class="lang-cs prettyprint-override"><code>/// &lt;summary&gt;Download a file based on its Id.&lt;/summary&gt;
  /// &lt;param name="id"&gt;Identity of file to download.&lt;/param&gt;
  /// &lt;returns&gt;&lt;see cref="MyFile" /&gt; file content found.&lt;/returns&gt;
  [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&lt;IActionResult&gt; 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 };
  }
  
  </code></pre>
  
  <p>As you can see, I'm using both ProducesResponseType and SwaggerResponse to describe the download method. I'm a bit confused as to the correct attribute to use - swagger response or produces response type?  Should I use both?  Why would I favor one over the other?</p>
  
  <p>Thanks for any pointers in advance! :)</p>