feat(api): added support for OpenAPI

Author: thorsten

API.md

@@ -1,5 +1,7 @@
 # REST API v3.0 for phpMyFAQ 4.0
 
+> This documentation will be migrated to the OpenAPI format during the 4.0 development cycle.
+
 phpMyFAQ offers interfaces to access phpMyFAQ installations with other clients like an iPhone App. phpMyFAQ includes a
 REST API and offers APIs for various services like fetching the phpMyFAQ version or doing a search against the
 phpMyFAQ installation.

CHANGELOG.md

@@ -12,15 +12,15 @@ This is a log of major user-visible changes in each phpMyFAQ release.
 - changed PHP requirement to PHP 8.2 or later (Thorsten)
 - changed rewrite rules for Apache and nginx as mandatory requirement (Thorsten)
 - changed folder structure (Thorsten, Jan Harms)
-- (WIP) added Twig as new template engine (Thorsten)
+- [WIP] added Twig as new template engine (Thorsten)
 - added Symfony Routing (Thorsten)
 - added new admin configuration frontend (Thorsten)
 - added new admin category management frontend with full drag and drop sorting support (Thorsten)
 - added new admin FAQ management frontend (Thorsten)
 - added possibility to sort sticky FAQs (Jan Harms)
 - added possibility to enable/disable cookie consent (Thorsten)
 - added experimental online update feature (Jan Harms, Thorsten)
-- added REST API v3.0 (Thorsten)
+- [WIP] added REST API v3.0 with OpenAPI specification (Thorsten)
 - added Kubernetes manifest samples (OWNDOMAINHOME SAS)
 - added experimental import of FAQs from CSV (Jan Harms)
 - added CSV export of user sessions (Jan Harms)

composer.json

@@ -50,7 +50,8 @@
     "phpunit/phpunit": "11.*",
     "rector/rector": "^1.0.0",
     "squizlabs/php_codesniffer": "3.*",
-    "symfony/yaml": "7.*"
+    "symfony/yaml": "7.*",
+    "zircote/swagger-php": "^4.8"
   },
   "suggest": {
     "ext-ldap": "*",
@@ -70,11 +71,17 @@
     },
     "sort-packages": true
   },
+  "autoload": {
+    "psr-4": {
+      "phpMyFAQ\\": "./phpmyfaq/src/phpMyFAQ"
+    }
+  },
   "minimum-stability": "stable",
   "scripts": {
     "check": "./phpmyfaq/src/libs/bin/phpstan analyse -c phpstan.neon --memory-limit 1G",
     "lint": "./phpmyfaq/src/libs/bin/phpcs --standard=PSR12 --extensions=php --ignore=./phpmyfaq/src/libs/* ./phpmyfaq/src/phpMyFAQ",
     "lint-fix": "./phpmyfaq/src/libs/bin/phpcbf --standard=PSR12 --extensions=php --ignore=./phpmyfaq/src/libs/* ./phpmyfaq/src/phpMyFAQ",
+    "openapi": "./phpmyfaq/src/libs/bin/openapi -b ./phpmyfaq/src/libs/autoload.php ./phpmyfaq/src/phpMyFAQ -o ./phpmyfaq/openapi.yaml",
     "phpstan": "./phpmyfaq/src/libs/bin/phpstan analyze --memory-limit=4G",
     "refactor": "./phpmyfaq/src/libs/bin/rector",
     "refactor:dryrun": "./phpmyfaq/src/libs/bin/rector --dry-run",

composer.lock

@@ -0,0 +1,57 @@
+openapi: 3.0.0
+info:
+  title: 'phpMyFAQ REST API'
+  contact:
+    name: 'phpMyFAQ Team'
+    email: [email protected]
+  license:
+    name: 'Mozilla Public Licence 2.0'
+    url: 'https://www.mozilla.org/MPL/2.0/'
+  version: '3.0'
+paths:
+  /api/v3.0/search:
+    get:
+      operationId: getSearch
+      responses:
+        '404':
+          description: 'If the search returns no results'
+          content:
+            application/json:
+              schema: {}
+              example: []
+  /api/v3.0/tags:
+    get:
+      operationId: getTags
+      responses:
+        '200':
+          description: 'Returns the tags for the given language provided by "Accept-Language".'
+          content:
+            application/json:
+              schema: {}
+              example: "[\n            {\"tagId\": 4, \"tagName\": \"phpMyFAQ\", \"tagFrequency\": 3 },\n            {\"tagId\": 1, \"tagName\": \"PHP 8\", \"tagFrequency\": 2 }\n        ]"
+        '404':
+          description: 'If no tags are stored.'
+          content:
+            application/json:
+              schema: {}
+              example: []
+  /api/v3.0/title:
+    get:
+      operationId: getTitle
+      responses:
+        '200':
+          description: 'Returns the title of the phpMyFAQ instance as a string.'
+          content:
+            application/json:
+              schema: {}
+              example: 'phpMyFAQ Codename Pontus'
+  /api/v3.0/version:
+    get:
+      operationId: getVersion
+      responses:
+        '200':
+          description: 'Returns the phpMyFAQ version number as string.'
+          content:
+            application/json:
+              schema: {}
+              example: 4.0.0

phpmyfaq/openapi.yaml

@@ -17,7 +17,9 @@
 
 namespace phpMyFAQ\Controller;
 
+use OpenApi\Attributes as OA;
 use phpMyFAQ\Configuration;
+use phpMyFAQ\Core\Exception;
 use phpMyFAQ\Enums\PermissionType;
 use phpMyFAQ\Template\TemplateException;
 use phpMyFAQ\Template\TwigWrapper;
@@ -26,12 +28,21 @@
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\HttpKernel\Exception\UnauthorizedHttpException;
 
+#[OA\Info(
+    version: '3.0',
+    title: 'phpMyFAQ REST API',
+    contact: new OA\Contact(
+        name: 'phpMyFAQ Team',
+        email: '[email protected]'
+    )
+)]
+#[OA\License(name: 'Mozilla Public Licence 2.0', url: 'https://www.mozilla.org/MPL/2.0/')]
 abstract class AbstractController
 {
     /**
      * Returns a Twig rendered template as response.
      *
-     * @param string[]      $templateVars
+     * @param string[] $templateVars
      * @param Response|null $response
      * @throws TemplateException
      */
@@ -48,6 +59,11 @@ protected function render(string $pathToTwigFile, array $templateVars = [], Resp
 
     /**
      * Returns a JsonResponse that uses json_encode().
+     *
+     * @param mixed $data
+     * @param int $status
+     * @param string[] $headers
+     * @return JsonResponse
      */
     protected function json(mixed $data, int $status = 200, array $headers = []): JsonResponse
     {
@@ -56,6 +72,7 @@ protected function json(mixed $data, int $status = 200, array $headers = []): Js
 
     /**
      * @throws UnauthorizedHttpException
+     * @throws Exception
      */
     protected function userIsAuthenticated(): void
     {
@@ -67,6 +84,7 @@ protected function userIsAuthenticated(): void
 
     /**
      * @throws UnauthorizedHttpException
+     * @throws Exception
      */
     protected function userIsSuperAdmin(): void
     {
@@ -78,6 +96,7 @@ protected function userIsSuperAdmin(): void
 
     /**
      * @throws UnauthorizedHttpException
+     * @throws Exception
      */
     protected function userHasGroupPermission(): void
     {
@@ -95,6 +114,7 @@ protected function userHasGroupPermission(): void
 
     /**
      * @throws UnauthorizedHttpException
+     * @throws Exception
      */
     protected function userHasUserPermission(): void
     {
@@ -111,6 +131,7 @@ protected function userHasUserPermission(): void
 
     /**
      * @throws UnauthorizedHttpException
+     * @throws Exception
      */
     protected function userHasPermission(PermissionType $permissionType): void
     {

phpmyfaq/src/phpMyFAQ/Controller/AbstractController.php

@@ -17,6 +17,7 @@
 
 namespace phpMyFAQ\Controller\Api;
 
+use OpenApi\Attributes as OA;
 use phpMyFAQ\Category;
 use phpMyFAQ\Configuration;
 use phpMyFAQ\Faq\FaqPermission;
@@ -34,6 +35,16 @@ class SearchController
     /**
      * @throws \Exception
      */
+    #[OA\Get(
+        path: '/api/v3.0/search',
+        operationId: 'getSearch'
+    )]
+
+    #[OA\Response(
+        response: 404,
+        description: 'If the search returns no results',
+        content: new OA\JsonContent(example: []),
+    )]
     public function search(Request $request): JsonResponse
     {
         $jsonResponse = new JsonResponse();