Merge pull request #2592 from tarlepp/feat/open-api-annotations-to-at…

…tributes Feat - Use Open API attributes instead of annotations
tarlepp · Dec 25, 2023 · 6dd1d17 · 6dd1d17
2 parents 1d7572d + ace5bf9
commit 6dd1d17
Show file tree

Hide file tree

Showing 27 changed files with 817 additions and 754 deletions.
diff --git a/src/Controller/HealthzController.php b/src/Controller/HealthzController.php
@@ -11,7 +11,9 @@
 use App\Rest\Interfaces\ResponseHandlerInterface;
 use App\Rest\ResponseHandler;
 use App\Utils\HealthzService;
-use OpenApi\Annotations as OA;
+use OpenApi\Attributes as OA;
+use OpenApi\Attributes\JsonContent;
+use OpenApi\Attributes\Property;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\HttpKernel\Attribute\AsController;
@@ -39,27 +41,34 @@ public function __construct(
      *
      * @see https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/
      *
-     * @OA\Get(
-     *     operationId="healthz",
-     *     responses={
-     *          @OA\Response(
-     *              response=200,
-     *              description="success",
-     *              @OA\Schema(
-     *                  type="object",
-     *                  example={"timestamp": "2018-01-01T13:08:05+00:00"},
-     *                  @OA\Property(property="timestamp", type="string"),
-     *              ),
-     *          ),
-     *     },
-     *  )
-     *
      * @throws Throwable
      */
     #[Route(
         path: '/healthz',
         methods: [Request::METHOD_GET],
     )]
+    #[OA\Get(
+        operationId: 'healthz',
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'success',
+                content: new JsonContent(
+                    properties: [
+                        new Property(
+                            property: 'timestamp',
+                            description: 'Timestamp when health check was performed',
+                            type: 'string',
+                        ),
+                    ],
+                    type: 'object',
+                    example: [
+                        'timestamp' => '2018-01-01T13:08:05+00:00',
+                    ],
+                ),
+            ),
+        ],
+    )]
     public function __invoke(Request $request): Response
     {
         return $this->responseHandler->createResponse(

diff --git a/src/Controller/VersionController.php b/src/Controller/VersionController.php
@@ -9,7 +9,9 @@
 namespace App\Controller;
 
 use App\Service\Version;
-use OpenApi\Annotations as OA;
+use OpenApi\Attributes as OA;
+use OpenApi\Attributes\JsonContent;
+use OpenApi\Attributes\Property;
 use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpKernel\Attribute\AsController;
@@ -30,27 +32,34 @@ public function __construct(
     }
 
     /**
-     * Route for get API version.
-     *
-     * @OA\Get(
-     *      operationId="version",
-     *      responses={
-     *          @OA\Response(
-     *               response=200,
-     *               description="success",
-     *               @OA\Schema(
-     *                   type="object",
-     *                   example={"version": "1.2.3"},
-     *                   @OA\Property(property="version", type="string", description="Version number"),
-     *               ),
-     *           ),
-     *      },
-     *  )
+     * Route to get API version.
      */
     #[Route(
         path: '/version',
         methods: [Request::METHOD_GET],
     )]
+    #[OA\Get(
+        operationId: 'version',
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'success',
+                content: new JsonContent(
+                    properties: [
+                        new Property(
+                            property: 'version',
+                            description: 'Version number of the API in semver format',
+                            type: 'string',
+                        ),
+                    ],
+                    type: 'object',
+                    example: [
+                        'version' => '1.2.3',
+                    ],
+                ),
+            ),
+        ],
+    )]
     public function __invoke(): JsonResponse
     {
         return new JsonResponse([

diff --git a/src/Controller/v1/ApiKey/ApiKeyController.php b/src/Controller/v1/ApiKey/ApiKeyController.php
@@ -14,7 +14,7 @@
 use App\Resource\ApiKeyResource;
 use App\Rest\Controller;
 use App\Rest\Traits\Actions;
-use OpenApi\Annotations as OA;
+use OpenApi\Attributes as OA;
 use Symfony\Component\HttpKernel\Attribute\AsController;
 use Symfony\Component\Routing\Annotation\Route;
 use Symfony\Component\Security\Core\Authorization\Voter\AuthenticatedVoter;
@@ -23,8 +23,6 @@
 /**
  * Class ApiKeyController
  *
- * @OA\Tag(name="ApiKey Management")
- *
  * @package App\Controller
  * @author TLe, Tarmo Leppänen <[email protected]>
  *
@@ -35,6 +33,7 @@
     path: '/v1/api_key',
 )]
 #[IsGranted(AuthenticatedVoter::IS_AUTHENTICATED_FULLY)]
+#[OA\Tag(name: 'ApiKey Management')]
 class ApiKeyController extends Controller
 {
     use Actions\Root\CountAction;

diff --git a/src/Controller/v1/Auth/GetTokenController.php b/src/Controller/v1/Auth/GetTokenController.php
@@ -10,7 +10,9 @@
 
 use App\Utils\JSON;
 use JsonException;
-use OpenApi\Annotations as OA;
+use OpenApi\Attributes as OA;
+use OpenApi\Attributes\JsonContent;
+use OpenApi\Attributes\Property;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\HttpKernel\Attribute\AsController;
@@ -30,52 +32,77 @@ class GetTokenController
     /**
      * Endpoint action to get user Json Web Token (JWT) for authentication.
      *
-     * @OA\RequestBody(
-     *      request="body",
-     *      description="Credentials object",
-     *      required=true,
-     *      @OA\Schema(
-     *          example={"username": "username", "password": "password"},
-     *      )
-     *  )
-     * @OA\Response(
-     *      response=200,
-     *      description="JSON Web Token for user",
-     *      @OA\Schema(
-     *          type="object",
-     *          example={"token": "_json_web_token_"},
-     *          @OA\Property(property="token", type="string", description="Json Web Token"),
-     *      ),
-     *  )
-     * @OA\Response(
-     *      response=400,
-     *      description="Bad Request",
-     *      @OA\Schema(
-     *          type="object",
-     *          example={"code": 400, "message": "Bad Request"},
-     *          @OA\Property(property="code", type="integer", description="Error code"),
-     *          @OA\Property(property="message", type="string", description="Error description"),
-     *      ),
-     *  )
-     * @OA\Response(
-     *      response=401,
-     *      description="Unauthorized",
-     *      @OA\Schema(
-     *          type="object",
-     *          example={"code": 401, "message": "Bad credentials"},
-     *          @OA\Property(property="code", type="integer", description="Error code"),
-     *          @OA\Property(property="message", type="string", description="Error description"),
-     *      ),
-     *  )
-     * @OA\Tag(name="Authentication")
-     *
      * @throws HttpException
      * @throws JsonException
      */
     #[Route(
         path: '/v1/auth/get_token',
         methods: [Request::METHOD_POST],
     )]
+    #[OA\RequestBody(
+        request: 'body',
+        description: 'Credentials object',
+        required: true,
+        content: new JsonContent(
+            properties: [
+                new Property(property: 'username', type: 'string'),
+                new Property(property: 'password', type: 'string'),
+            ],
+            type: 'object',
+            example: [
+                'username' => 'username',
+                'password' => 'password',
+            ],
+        ),
+    )]
+    #[OA\Response(
+        response: 200,
+        description: 'JSON Web Token for user',
+        content: new JsonContent(
+            properties: [
+                new Property(
+                    property: 'token',
+                    description: 'Json Web Token',
+                    type: 'string',
+                ),
+            ],
+            type: 'object',
+            example: [
+                'token' => '_json_web_token_',
+            ],
+        ),
+    )]
+    #[OA\Response(
+        response: 400,
+        description: 'Bad Request',
+        content: new JsonContent(
+            properties: [
+                new Property(property: 'code', type: 'integer'),
+                new Property(property: 'message', type: 'string'),
+            ],
+            type: 'object',
+            example: [
+                'code' => 400,
+                'message' => 'Bad Request',
+            ],
+        ),
+    )]
+    #[OA\Response(
+        response: 401,
+        description: 'Unauthorized',
+        content: new JsonContent(
+            properties: [
+                new Property(property: 'code', type: 'integer'),
+                new Property(property: 'message', type: 'string'),
+            ],
+            type: 'object',
+            example: [
+                'code' => 401,
+                'message' => 'Bad credentials',
+            ],
+        ),
+    )]
+    #[OA\Tag(name: 'Authentication')]
     public function __invoke(): never
     {
         $message = sprintf(

diff --git a/src/Controller/v1/Localization/LanguageController.php b/src/Controller/v1/Localization/LanguageController.php
@@ -9,7 +9,8 @@
 namespace App\Controller\v1\Localization;
 
 use App\Service\Localization;
-use OpenApi\Annotations as OA;
+use OpenApi\Attributes as OA;
+use OpenApi\Attributes\JsonContent;
 use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpKernel\Attribute\AsController;
@@ -18,12 +19,11 @@
 /**
  * Class LanguageController
  *
- * @OA\Tag(name="Localization")
- *
  * @package App\Controller\v1\Localization
  * @author TLe, Tarmo Leppänen <[email protected]>
  */
 #[AsController]
+#[OA\Tag(name: 'Localization')]
 class LanguageController
 {
     public function __construct(
@@ -34,21 +34,23 @@ public function __construct(
     /**
      * Endpoint action to get supported languages. This is for use to choose
      * what language your frontend application can use within its translations.
-     *
-     * @OA\Response(
-     *      response=200,
-     *      description="List of language strings.",
-     *      @OA\Schema(
-     *          type="array",
-     *          example={"en","fi"},
-     *          @OA\Items(type="string"),
-     *      ),
-     *  )
      */
     #[Route(
         path: '/v1/localization/language',
         methods: [Request::METHOD_GET],
     )]
+    #[OA\Response(
+        response: 200,
+        description: 'List of language strings.',
+        content: new JsonContent(
+            type: 'array',
+            items: new OA\Items(
+                type: 'string',
+                example: 'en',
+            ),
+            example: ['en', 'fi'],
+        ),
+    )]
     public function __invoke(): JsonResponse
     {
         return new JsonResponse($this->localization->getLanguages());

diff --git a/src/Controller/v1/Localization/LocaleController.php b/src/Controller/v1/Localization/LocaleController.php
@@ -9,7 +9,8 @@
 namespace App\Controller\v1\Localization;
 
 use App\Service\Localization;
-use OpenApi\Annotations as OA;
+use OpenApi\Attributes as OA;
+use OpenApi\Attributes\JsonContent;
 use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpKernel\Attribute\AsController;
@@ -18,12 +19,11 @@
 /**
  * Class LocaleController
  *
- * @OA\Tag(name="Localization")
- *
  * @package App\Controller\v1\Localization
  * @author TLe, Tarmo Leppänen <[email protected]>
  */
 #[AsController]
+#[OA\Tag(name: 'Localization')]
 class LocaleController
 {
     public function __construct(
@@ -35,21 +35,23 @@ public function __construct(
      * Endpoint action to get supported locales. This is for use to choose what
      * locale your frontend application can use within its number, time, date,
      * datetime, etc. formatting.
-     *
-     * @OA\Response(
-     *      response=200,
-     *      description="List of locale strings.",
-     *      @OA\Schema(
-     *          type="array",
-     *          example={"en","fi"},
-     *          @OA\Items(type="string"),
-     *      ),
-     *  )
      */
     #[Route(
         path: '/v1/localization/locale',
         methods: [Request::METHOD_GET],
     )]
+    #[OA\Response(
+        response: 200,
+        description: 'List of locale strings.',
+        content: new JsonContent(
+            type: 'array',
+            items: new OA\Items(
+                type: 'string',
+                example: 'en',
+            ),
+            example: ['en', 'fi'],
+        ),
+    )]
     public function __invoke(): JsonResponse
     {
         return new JsonResponse($this->localization->getLocales());