Add OpenAPI docs (#1)

* Install nelmio api doc bundle

* Add openapi docs

* cq

* Move nelmio apidoc bundle configurations to dev configs

backend/.gitignore

@@ -4,7 +4,7 @@
 /.env.local.php
 /.env.*.local
 /config/secrets/prod/prod.decrypt.private.php
-/public/bundles/
+/public/api/assets/bundles
 /var/
 /vendor/
 ###< symfony/framework-bundle ###
@@ -26,7 +26,3 @@ phpstan.neon
 /phpunit.xml
 ###< symfony/phpunit-bridge ###
 
-###> phpunit/phpunit ###
-/phpunit.xml
-.phpunit.result.cache
-###< phpunit/phpunit ###

backend/composer.json

@@ -32,21 +32,24 @@
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3.54",
+        "nelmio/api-doc-bundle": "^4.26",
         "phpstan/phpstan": "^1.10",
         "phpstan/phpstan-doctrine": "^1.3",
         "phpstan/phpstan-symfony": "^1.3",
         "phpunit/phpunit": "^11.1",
+        "symfony/asset": "6.4.*",
         "symfony/browser-kit": "6.4.*",
         "symfony/css-selector": "6.4.*",
         "symfony/debug-bundle": "6.4.*",
         "symfony/phpunit-bridge": "^7.0",
         "symfony/stopwatch": "6.4.*",
+        "symfony/twig-bundle": "6.4.*",
         "symfony/web-profiler-bundle": "6.4.*"
     },
     "scripts": {
         "auto-scripts": {
             "cache:clear": "symfony-cmd",
-            "assets:install %PUBLIC_DIR%": "symfony-cmd"
+            "assets:install %PUBLIC_DIR%/api/assets": "symfony-cmd"
         },
         "post-install-cmd": [
             "@auto-scripts"

backend/config/bundles.php

@@ -10,4 +10,5 @@
     Symfony\Bundle\WebProfilerBundle\WebProfilerBundle::class => ['dev' => true, 'test' => true],
     Symfony\Bundle\MonologBundle\MonologBundle::class => ['all' => true],
     Symfony\Bundle\DebugBundle\DebugBundle::class => ['dev' => true],
+    Nelmio\ApiDocBundle\NelmioApiDocBundle::class => ['dev' => true],
 ];

backend/config/packages/dev/assets.yaml

@@ -0,0 +1,3 @@
+framework:
+    assets:
+        base_path: /api/assets

backend/config/packages/dev/nelmio_api_doc.yaml

@@ -0,0 +1,11 @@
+nelmio_api_doc:
+    html_config:
+        assets_mode: cdn
+    documentation:
+        info:
+            title: Flexhub
+            description: Private storage for symfony/flex recipes
+            version: 0.x.x
+    areas: # to filter documented areas
+        path_patterns:
+            - ^\/api(?!\/doc$|\/_wdt\/|\/_profiler\/) # Accepts routes under /api except /api/doc, /api/_wdt/*, /api/_profiler/*

backend/config/routes/dev/nelmio_api_doc.yaml

@@ -0,0 +1,12 @@
+# Expose your documentation as JSON swagger compliant
+app.swagger:
+    path: /api/doc.json
+    methods: GET
+    defaults: { _controller: nelmio_api_doc.controller.swagger }
+
+## Requires the Asset component and the Twig bundle
+## $ composer require twig asset
+app.swagger_ui:
+    path: /api/doc
+    methods: GET
+    defaults: { _controller: nelmio_api_doc.controller.swagger_ui }

backend/src/Controller/Api/FlexController.php

@@ -5,6 +5,7 @@
 namespace App\Controller\Api;
 
 use App\Flex\Index\IndexLoaderInterface;
+use OpenApi\Attributes as OA;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\Routing\Annotation\Route;
@@ -13,6 +14,7 @@
  * @phpstan-import-type FlexIndex from IndexLoaderInterface
  */
 #[Route('/flex')]
+#[OA\Tag('Flex')]
 final class FlexController extends AbstractController
 {
     /** @return FlexIndex */