org.sonar.plugins.csharp.S6968.html Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of sonar-csharp-plugin Show documentation
Code Analyzer for C#
There is a newer version: 10.2.0.105762
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