feat(api): more OpenAPI documentation

Author: thorsten

API.md

@@ -28,7 +28,7 @@ Public endpoints require no Authentication.
 ### FAQ related APIs
 
 - Attachments: `GET /api/v3.0/attachments`
-- [Comments](api-docs/comments.md): `GET /api/v3.0/comments`
+- Comments: `GET /api/v3.0/comments`
 - [All FAQs](api-docs/faqs.md): `GET /api/v3.0/faqs`
 - [All FAQs per Category](api-docs/faqs/categoryId.md): `GET /api/v3.0/faqs/:categoryId`
 - [All FAQs per Tags](api-docs/faqs/tags.md): `GET /api/v3.0/faqs/tags/:tagId`
@@ -59,7 +59,7 @@ be acquired from the admin configuration.
 
 ### Groups related APIs
 
-- [All groups](api-docs/groups.md): `GET /api/v3.0/groups`
+- All groups: `GET /api/v3.0/groups`
 
 ### Login/Registration related APIs
 

api-docs/comments.md

@@ -77,6 +77,67 @@ paths:
             application/json:
               schema: {}
               example: []
+  '/api/v3.0/comments/{faqId}':
+    get:
+      tags:
+        - 'Public Endpoints'
+      description: 'Returns a list of comments for a given FAQ record ID.'
+      operationId: getComments
+      parameters:
+        - name: faqId
+          in: path
+          description: 'The FAQ record ID.'
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 'If the FAQ has at least one comment.'
+          headers:
+            Accept-Language:
+              description: 'The language code for the login.'
+              schema:
+                type: string
+          content:
+            application/json:
+              schema: {}
+              example: "\n        [\n            {\n                \"id\": 2,\n                \"recordId\": 142,\n                \"categoryId\": null,\n                \"type\": \"faq\",\n                \"username\": \"phpMyFAQ User\",\n                \"email\": \"[email protected]\",\n                \"comment\": \"Foo! Bar?\",\n                \"date\": \"2019-12-24T12:24:57+0100\",\n                \"helped\": null\n            }\n        ]"
+        '404':
+          description: 'If the FAQ has no comments.'
+          headers:
+            Accept-Language:
+              description: 'The language code for the login.'
+              schema:
+                type: string
+          content:
+            application/json:
+              schema: {}
+              example: []
+  /api/v3.0/groups:
+    get:
+      tags:
+        - 'Endpoints with Authentication'
+      description: 'Used to fetch all group IDs.'
+      operationId: getGroups
+      responses:
+        '200':
+          description: 'Returns a list of group IDs.'
+          headers:
+            Accept-Language:
+              description: 'The language code for the login.'
+              schema:
+                type: string
+          content:
+            application/json:
+              schema: {}
+              example: "\n        [\n            {\n                \"group-id\": 1\n            },\n            {\n                \"group-id\": 2\n            }\n        ]"
+        '401':
+          description: 'If the user is not authenticated.'
+          headers:
+            Accept-Language:
+              description: 'The language code for the login.'
+              schema:
+                type: string
   /api/v3.0/language:
     get:
       tags:

api-docs/groups.md

@@ -17,6 +17,7 @@
 
 namespace phpMyFAQ\Controller\Api;
 
+use OpenApi\Attributes as OA;
 use phpMyFAQ\Comments;
 use phpMyFAQ\Configuration;
 use phpMyFAQ\Entity\CommentType;
@@ -27,6 +28,47 @@
 
 class CommentController
 {
+    #[OA\Get(
+        path: '/api/v3.0/comments/{faqId}',
+        operationId: 'getComments',
+        description: 'Returns a list of comments for a given FAQ record ID.',
+        tags: ['Public Endpoints']
+    )]
+    #[OA\Header(
+        header: 'Accept-Language',
+        description: 'The language code for the login.',
+        schema: new OA\Schema(type: 'string')
+    )]
+    #[OA\Parameter(
+        name: 'faqId',
+        description: 'The FAQ record ID.',
+        in: 'path',
+        required: true,
+        schema: new OA\Schema(type: 'integer')
+    )]
+    #[OA\Response(
+        response: 200,
+        description: 'If the FAQ has at least one comment.',
+        content: new OA\JsonContent(example: '
+        [
+            {
+                "id": 2,
+                "recordId": 142,
+                "categoryId": null,
+                "type": "faq",
+                "username": "phpMyFAQ User",
+                "email": "[email protected]",
+                "comment": "Foo! Bar?",
+                "date": "2019-12-24T12:24:57+0100",
+                "helped": null
+            }
+        ]')
+    )]
+    #[OA\Response(
+        response: 404,
+        description: 'If the FAQ has no comments.',
+        content: new OA\JsonContent(example: []),
+    )]
     public function list(Request $request): JsonResponse
     {
         $jsonResponse = new JsonResponse();

api-docs/openapi.yaml

@@ -17,16 +17,52 @@
 
 namespace phpMyFAQ\Controller\Api;
 
+use OpenApi\Attributes as OA;
 use phpMyFAQ\Configuration;
+use phpMyFAQ\Controller\AbstractController;
+use phpMyFAQ\Core\Exception;
 use phpMyFAQ\Permission\MediumPermission;
 use phpMyFAQ\User\CurrentUser;
 use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\HttpFoundation\Response;
 
-class GroupController
+class GroupController extends AbstractController
 {
+    /**
+     * @throws Exception
+     */
+    #[OA\Get(
+        path: '/api/v3.0/groups',
+        operationId: 'getGroups',
+        description: 'Used to fetch all group IDs.',
+        tags: ['Endpoints with Authentication']
+    )]
+    #[OA\Header(
+        header: 'Accept-Language',
+        description: 'The language code for the login.',
+        schema: new OA\Schema(type: 'string')
+    )]
+    #[OA\Response(
+        response: 200,
+        description: 'Returns a list of group IDs.',
+        content: new OA\JsonContent(example: '
+        [
+            {
+                "group-id": 1
+            },
+            {
+                "group-id": 2
+            }
+        ]')
+    )]
+    #[OA\Response(
+        response: 401,
+        description: 'If the user is not authenticated.'
+    )]
     public function list(): JsonResponse
     {
+        $this->userIsAuthenticated();
+
         $jsonResponse = new JsonResponse();
         $faqConfig = Configuration::getConfigurationInstance();
         $user = CurrentUser::getCurrentUser($faqConfig);