Setup Open API documentation.

koencaerels · Apr 25, 2024 · b88b8ab · b88b8ab
1 parent 5dbb2ee
commit b88b8ab
Show file tree

Hide file tree

Showing 21 changed files with 5,312 additions and 696 deletions.
diff --git a/...and/Member/MarkSubscriptionAsPayedFromMollie/MarkSubscriptionAsPayedFromMollieHandler.php b/...and/Member/MarkSubscriptionAsPayedFromMollie/MarkSubscriptionAsPayedFromMollieHandler.php
@@ -36,7 +36,7 @@ public function __construct(
     // Handler
     // —————————————————————————————————————————————————————————————————————————
 
-    public function go(MarkSubscriptionAsPayedFromMollie $command): int|null
+    public function go(MarkSubscriptionAsPayedFromMollie $command): ?int
     {
         $result = false;
         $subscription = $this->subscriptionRepository->findByPaymentId($command->getPaymentId());

diff --git a/application/YoshiKan/Infrastructure/CLI/CreateApiDocumentation.php b/application/YoshiKan/Infrastructure/CLI/CreateApiDocumentation.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\YoshiKan\Infrastructure\CLI;
+
+use Nelmio\ApiDocBundle\ApiDocGenerator;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+class CreateApiDocumentation extends Command
+{
+    // ——————————————————————————————————————————————————————————————————————————
+    // Constructor
+    // ——————————————————————————————————————————————————————————————————————————
+
+    public function __construct(private ApiDocGenerator $apiDocGenerator)
+    {
+        parent::__construct('openapi:gen');
+    }
+
+    // ——————————————————————————————————————————————————————————————————————————
+    // Executor
+    // ——————————————————————————————————————————————————————————————————————————
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $output->writeln('Start generating OpenAPI documentation');
+        $documentation = $this->apiDocGenerator->generate();
+        $json = json_encode($documentation, \JSON_PRETTY_PRINT);
+        $jsonPath = './frontends/member_module/src/api/client/schema.json';
+        file_put_contents($jsonPath, $json);
+        $output->writeln('Done generating OpenAPI documentation');
+
+        return Command::SUCCESS;
+    }
+}
diff --git a/application/YoshiKan/Infrastructure/Templates/api/api_documentation.html.twig b/application/YoshiKan/Infrastructure/Templates/api/api_documentation.html.twig
@@ -0,0 +1,23 @@
+<!doctype html>
+<html>
+<head>
+    <title>Yoshi Kan - API Reference</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+</head>
+<body>
+<script id="api-reference" data-url="{{ path('api_documentation_schema') }}"></script>
+{# data-proxy-url="https://api.scalar.com/request-proxy"
+    <!-- You can also set a full configuration object like this -->
+    <!-- easier for nested objects -->
+#}
+<script>
+    var configuration = {
+        theme: 'purple',
+    }
+    var apiReference = document.getElementById('api-reference')
+    apiReference.dataset.configuration = JSON.stringify(configuration)
+</script>
+<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body>
+</html>
diff --git a/application/YoshiKan/Infrastructure/Web/Controller/ApiController.php b/application/YoshiKan/Infrastructure/Web/Controller/ApiController.php
@@ -118,11 +118,29 @@ private function setTwigLoader(KernelInterface $appKernel): void
         }
     }
 
+    // ———————————————————————————————————————————————————————————————————————————
+    // API Documentation
+    // ———————————————————————————————————————————————————————————————————————————
+
+    #[Route('/mm/api/docs', name: 'api_documentation', condition: '%kernel.debug% === 1')]
+    public function apiDocumentation(): Response
+    {
+        return $this->render('api/api_documentation.html.twig');
+    }
+
+    #[Route('/mm/api/docs/schema', name: 'api_documentation_schema', condition: '%kernel.debug% === 1')]
+    public function apiDocumentationSchema(): JsonResponse
+    {
+        $schemaFile = $this->appKernel->getProjectDir().'/frontends/member_module/src/api/client/schema.json';
+
+        return new JsonResponse(json_decode(file_get_contents($schemaFile)), 200, $this->apiAccess);
+    }
+
     // ———————————————————————————————————————————————————————————————————————————
     // Index
     // ———————————————————————————————————————————————————————————————————————————
 
-    #[Route('/inschrijving/api', name: 'inschrijving_api_index')]
+    #[Route('/inschrijving/api', name: 'inschrijving_api_index', condition: '%kernel.debug% === 1')]
     public function index(): JsonResponse
     {
         $response = 'Api endpoint for subscriptions';

diff --git a/bin/console b/bin/console
diff --git a/bin/phpunit b/bin/phpunit
diff --git a/bin/post-create-project.php b/bin/post-create-project.php
diff --git a/composer.json b/composer.json
@@ -42,6 +42,7 @@
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3.13",
         "mockery/mockery": "^1.6",
+        "nelmio/api-doc-bundle": "^4.26",
         "pestphp/pest": "^1.23",
         "phpstan/phpstan": "^1.9.0",
         "phpstan/phpstan-doctrine": "^1.3.0",