We’re using php-swagger for OpenAPI annotations, but sonarcloud/sonarlint detects comment blocks as a code-smell under rule php:S125 if using the description+markdown from comments extraction support.
This example triggers the code smell and the entire comment block gets marked as commented out code under rule php:S125. After further investigation it seems that the ## Header is what is triggering the code-smell.
use OpenApi\Annotations as OA;
class ExampleController {
/**
* ## The example endpoint.
*
* This *demonstrates* issues with OpenAPI documentation while using [SonarLint](https://community.sonarsource.com/).
*
* @OA\Get(
* path="/api/some/endpoint",
* operationId="getSomeEndpoint",
* tags={"Example"},
* summary="Does something",
* description="One-line markdown is not fun"
* @OA\Response(
* response=201,
* description="Successfully succeeded"
* )
* )
*
* @return void
*/
public function getSomething(): void
{
//
}
}
This example does not trigger a code-smell.
use OpenApi\Annotations as OA;
class ExampleController {
/**
* *This* is apparently fine with SonarCloud/Lint.
*
* @OA\Get(
* path="/api/some/endpoint",
* operationId="getSomeEndpoint",
* tags={"Example"},
* summary="Does something",
* description="One-line markdown is not fun"
* @OA\Response(
* response=201,
* description="Successfully succeeded"
* )
* )
*
* @return void
*/
public function getSomething(): void
{
//
}
}
The library used for annotations:
Edit: I did some further investigation, and it seems that the markdown headers is what triggers the code-smell, and potentially other markdown syntax. Updated the description and title to reflect that.