Creo que puede ser útil para los códigos de retorno que no son correctos (200). Digamos que si uno de los códigos de estado de falla devuelve un modelo que describe el problema, puede especificar que el código de estado en ese caso produzca algo diferente al caso de éxito. Puede leer más sobre eso y encontrar ejemplos aquí: https://docs.microsoft.com/en-us/aspnet/core/web-api/action-return-types?view=aspnetcore-2.2

Es para producir metadatos de API abierta para herramientas de exploración/visualización de API como Swagger ( https://swagger.io/ ), para indicar en la documentación lo que el controlador puede devolver.

Aunque ya se envió la respuesta correcta, me gustaría dar un ejemplo. Suponga que ha agregado el paquete Swashbuckle.AspNetCore a su proyecto y lo ha usado en Startup.Configure(...) así:

 app.UseSwagger(); app.UseSwaggerUI(options => { options.SwaggerEndpoint("/swagger/v1/swagger.json", "My Web Service API V1"); options.RoutePrefix = "api/docs"; });

Tener un punto final de acción del controlador de prueba como este:

 [HttpGet] public ActionResult GetAllItems() { if ((new Random()).Next() % 2 == 0) { return Ok(new string[] { "value1", "value2" }); } else { return Problem(detail: "No Items Found, Don't Try Again!"); } }

Dará como resultado una tarjeta/sección de interfaz de usuario de Swagger como esta (Ejecute el proyecto y vaya a /api/docs/index.html):

Como puede ver, no se proporcionan "metadatos" para el punto final.

Ahora, actualice el punto final a esto:

 [HttpGet] [ProducesResponseType(typeof(IEnumerable<string>), 200)] [ProducesResponseType(404)] public ActionResult GetAllItems() { if ((new Random()).Next() % 2 == 0) { return Ok(new string[] { "value1", "value2" }); } else { return Problem(detail: "No Items Found, Don't Try Again!"); } }

Esto no cambiará en absoluto el comportamiento de su terminal, pero ahora la página de swagger se ve así:

Esto es mucho mejor, porque ahora el cliente puede ver cuáles son los posibles códigos de estado de respuesta y, para cada estado de respuesta, cuál es el tipo/estructura de los datos devueltos. Tenga en cuenta que, aunque no he definido el tipo de devolución para 404, ASP.NET Core (estoy usando .NET 5) es lo suficientemente inteligente como para establecer el tipo de devolución en ProblemDetails .

Si este es el camino que desea tomar, es una buena idea agregar Web API Analyzer a su proyecto para recibir algunas advertencias útiles.

ps También me gustaría usar options.DisplayOperationId(); en la configuración app.UseSwaggerUI(...). Al hacerlo, la interfaz de usuario de Swagger mostrará el nombre del método .NET real que se asigna a cada punto final. Por ejemplo, el punto final anterior es un GET a /api/sample pero el método .NET real se llama GetAllItems()