In an ASP.NET Core Web API, controller actions can optionally return a result value. If a controller action returns a value in the happy path, for example ControllerBase.Ok(Object), annotating the action with one of the [ProducesResponseType] overloads that describe the type is recommended.

Why is this an issue?

If an ASP.NET Core Web API uses Swagger, the API documentation will be generated based on the input/output types of the controller actions, as well as the attributes annotating the actions. If an action returns IActionResult or IResult, Swagger cannot infer the type of the response. From the consumer’s perspective, this can be confusing and lead to unexpected results and bugs in the long run without the API provider’s awareness.

This rule raises an issue on a controller action when:

• The action returns a value in the happy path. This can be either:
  • 200 OK
  • 201 Created
  • 202 Accepted
• There is no [ProducesResponseType] attribute containing the return type, either at controller or action level.
• There is no [SwaggerResponse] attribute containing the return type, either at controller or action level.
• The controller is annotated with the [ApiController] attribute.
• The controller action returns either IActionResult or IResult.
• The application has enabled the Swagger middleware.

How to fix it

There are multiple ways to fix this issue:

• Annotate the action with [ProducesResponseType] containing the return type.
• Annotate the action with SwaggerResponse Class containing the return type.
• Return ActionResult<TValue> instead of [IActionResult] or [IResult].
• Return Results<TResult1, TResult2> instead of [IActionResult] or [IResult].

Code examples

Noncompliant code example

[HttpGet("foo")]
// Noncompliant: Annotate this method with ProducesResponseType containing the return type for succesful responses.
public IActionResult MagicNumber() => Ok(42);

[HttpGet("foo")]
// Noncompliant: Use the ProducesResponseType overload containing the return type for succesful responses.
[ProducesResponseType(StatusCodes.Status200OK)]
public IActionResult MagicNumber() => Ok(42);

Compliant solution

[HttpGet("foo")]
[ProducesResponseType<int>(StatusCodes.Status200OK)]
public IActionResult MagicNumber() => Ok(42);

[HttpGet("foo")]
[ProducesResponseType(typeof(int), StatusCodes.Status200OK)]
public IActionResult MagicNumber() => Ok(42);

Resources

Documentation

• Wikipedia - Web API
• Wikipedia - Happy path
• Microsoft Learn - ASP.NET Core
• Microsoft Learn - Get started with Swashbuckle and ASP.NET Core
• Microsoft Learn - ApiControllerAttribute Class
• Microsoft Learn - ProducesResponseTypeAttribute Class
• Microsoft Learn - ProducesResponseTypeAttribute<T> Class
• Microsoft Learn - ActionResult<TValue> Class
• Microsoft Learn - Results<TResult1, TResult2> Class
• Microsoft Learn - HttpResults type
• GitHub - SwaggerResponse Class
• SmartBear - Swagger