ISSUE-344: api doc

Author: tatevikg1

composer.json

@@ -31,7 +31,7 @@
     },
     "require": {
         "php": "^8.1",
-        "phplist/core": "dev-ISSUE-337",
+        "phplist/core": "5.0.0-alpha1",
         "friendsofsymfony/rest-bundle": "*",
         "symfony/test-pack": "^1.0",
         "symfony/process": "^6.4",
@@ -85,9 +85,6 @@
         ]
     },
     "extra": {
-        "branch-alias": {
-            "dev-ISSUE-337": "5.0.x-dev"
-        },
         "symfony-app-dir": "bin",
         "symfony-bin-dir": "bin",
         "symfony-var-dir": "var",

docs/.gitkeep

@@ -267,11 +267,11 @@ public function deleteList(
         return new JsonResponse(null, Response::HTTP_NO_CONTENT, [], false);
     }
 
-    #[Route('/lists/{id}/members', name: 'get_subscriber_from_list', methods: ['GET'])]
+    #[Route('/lists/{id}/subscribers', name: 'get_subscriber_from_list', methods: ['GET'])]
     #[OA\Get(
-        path: '/lists/{list}/members',
+        path: '/lists/{list}/subscribers',
         description: 'Returns a JSON list of all subscribers for a subscriber list.',
-        summary: 'Gets a list of all subscribers (members) of a subscriber list.',
+        summary: 'Gets a list of all subscribers of a subscriber list.',
         tags: ['lists'],
         parameters: [
             new OA\Parameter(

openapi.yaml

@@ -39,7 +39,7 @@ public function __construct(
 
     #[Route('/subscribers', name: 'create_subscriber', methods: ['POST'])]
     #[OA\Post(
-        path: '/subscriber',
+        path: '/subscribers',
         description: 'Creates a new subscriber (if there is no subscriber with the given email address yet).',
         summary: 'Create a subscriber',
         requestBody: new OA\RequestBody(
@@ -49,10 +49,8 @@ public function __construct(
                 required: ['email'],
                 properties: [
                     new OA\Property(property: 'email', type: 'string', format: 'string', example: 'admin@example.com'),
-                    new OA\Property(property: 'confirmed', type: 'boolean', example: false),
-                    new OA\Property(property: 'blacklisted', type: 'boolean', example: false),
+                    new OA\Property(property: 'request_confirmation', type: 'boolean', example: false),
                     new OA\Property(property: 'html_email', type: 'boolean', example: false),
-                    new OA\Property(property: 'disabled', type: 'boolean', example: false)
                 ]
             )
         ),
@@ -140,13 +138,14 @@ public function postAction(Request $request, SerializerInterface $serializer): J
         if ($this->subscriberRepository->findOneByEmail($email) !== null) {
             throw new ConflictHttpException('This resource already exists.', null, 1513439108);
         }
+        $confirmed = (bool)$data->get('request_confirmation', true);
         // @phpstan-ignore-next-line
         $subscriber = new Subscriber();
         $subscriber->setEmail($email);
-        $subscriber->setConfirmed((bool)$data->get('confirmed', false));
-        $subscriber->setBlacklisted((bool)$data->get('blacklisted', false));
+        $subscriber->setConfirmed(!$confirmed);
+        $subscriber->setBlacklisted(false);
         $subscriber->setHtmlEmail((bool)$data->get('html_email', true));
-        $subscriber->setDisabled((bool)$data->get('disabled', false));
+        $subscriber->setDisabled(false);
 
         $this->subscriberRepository->save($subscriber);
 
@@ -173,7 +172,7 @@ private function validateSubscriber(Request $request): void
             $invalidFields[] = 'email';
         }
 
-        $booleanFields = ['confirmed', 'blacklisted', 'html_email', 'disabled'];
+        $booleanFields = ['request_confirmation', 'html_email'];
         foreach ($booleanFields as $fieldKey) {
             if ($request->getPayload()->get($fieldKey) !== null
                 && !is_bool($request->getPayload()->get($fieldKey))

src/Controller/ListController.php

@@ -180,7 +180,7 @@ public function testGetListMembersForExistingListWithoutSessionKeyReturnsForbidd
     {
         $this->loadFixtures([SubscriberListFixture::class]);
 
-        self::getClient()->request('get', '/api/v2/lists/1/members');
+        self::getClient()->request('get', '/api/v2/lists/1/subscribers');
 
         $this->assertHttpForbidden();
     }
@@ -195,7 +195,7 @@ public function testGetListMembersForExistingListWithExpiredSessionKeyReturnsFor
 
         self::getClient()->request(
             'get',
-            '/api/v2/lists/1/members',
+            '/api/v2/lists/1/subscribers',
             [],
             [],
             ['PHP_AUTH_USER' => 'unused', 'PHP_AUTH_PW' => 'cfdf64eecbbf336628b0f3071adba763']
@@ -206,7 +206,7 @@ public function testGetListMembersForExistingListWithExpiredSessionKeyReturnsFor
 
     public function testGetListMembersWithCurrentSessionKeyForInexistentListReturnsNotFoundStatus()
     {
-        $this->authenticatedJsonRequest('get', '/api/v2/lists/999/members');
+        $this->authenticatedJsonRequest('get', '/api/v2/lists/999/subscribers');
 
         $this->assertHttpNotFound();
     }
@@ -215,7 +215,7 @@ public function testGetListMembersWithCurrentSessionKeyForExistingListReturnsOka
     {
         $this->loadFixtures([SubscriberListFixture::class]);
 
-        $this->authenticatedJsonRequest('get', '/api/v2/lists/1/members');
+        $this->authenticatedJsonRequest('get', '/api/v2/lists/1/subscribers');
 
         $this->assertHttpOkay();
     }
@@ -224,7 +224,7 @@ public function testGetListMembersWithCurrentSessionKeyForExistingListWithoutSub
     {
         $this->loadFixtures([SubscriberListFixture::class]);
 
-        $this->authenticatedJsonRequest('get', '/api/v2/lists/1/members');
+        $this->authenticatedJsonRequest('get', '/api/v2/lists/1/subscribers');
 
         $this->assertJsonResponseContentEquals([]);
     }
@@ -233,7 +233,7 @@ public function testGetListMembersWithCurrentSessionKeyForExistingListWithSubscr
     {
         $this->loadFixtures([SubscriberListFixture::class, SubscriberFixture::class, SubscriptionFixture::class]);
 
-        $this->authenticatedJsonRequest('get', '/api/v2/lists/2/members');
+        $this->authenticatedJsonRequest('get', '/api/v2/lists/2/subscribers');
 
         $this->assertJsonResponseContentEquals(
             [

src/Controller/SubscriberController.php

@@ -106,14 +106,10 @@ public static function invalidSubscriberDataProvider(): array
             'email is an empty string' => [['email' => '']],
             'email is invalid string' => [['email' => 'coffee and cigarettes']],
             'email as boolean' => [['email' => true]],
-            'confirmed as integer' => [['email' => 'kate@example.com', 'confirmed' => 1]],
-            'confirmed as string' => [['email' => 'kate@example.com', 'confirmed' => 'yes']],
-            'blacklisted as integer' => [['email' => 'kate@example.com', 'blacklisted' => 1]],
-            'blacklisted as string' => [['email' => 'kate@example.com', 'blacklisted' => 'yes']],
             'html_email as integer' => [['email' => 'kate@example.com', 'html_email' => 1]],
             'html_email as string' => [['email' => 'kate@example.com', 'html_email' => 'yes']],
-            'disabled as integer' => [['email' => 'kate@example.com', 'disabled' => 1]],
-            'disabled as string' => [['email' => 'kate@example.com', 'disabled' => 'yes']],
+            'request_confirmation as string' => [['email' => 'kate@example.com', 'request_confirmation' => 'needed']],
+            'disabled as string' => [['email' => 'kate@example.com', 'request_confirmation' => 1]],
         ];
     }
 
@@ -144,9 +140,9 @@ public function testPostSubscribersWithValidSessionKeyAssignsProvidedSubscriberD
         $responseContent = $this->getDecodedJsonResponseContent();
 
         static::assertSame($email, $responseContent['email']);
-        static::assertTrue($responseContent['confirmed']);
-        static::assertTrue($responseContent['blacklisted']);
+        static::assertFalse($responseContent['confirmed']);
+        static::assertFalse($responseContent['blacklisted']);
         static::assertTrue($responseContent['html_email']);
-        static::assertTrue($responseContent['disabled']);
+        static::assertFalse($responseContent['disabled']);
     }
 }