Merge pull request #214 from ember-nexus/github-issue/208

Add documentation and automatic documentation tests for endpoint DELE…

CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+### Added
+- Add documentation and automatic documentation tests for endpoint DELETE `/token`, closes #208.
 ### Changed
 - Remove commented and unused code, configuration etc., closes #168.
 ### Fixed

composer.json

@@ -96,6 +96,7 @@
     "test:unit": "php vendor/phpunit/phpunit/phpunit",
     "test:feature": "php bin/console cache:clear && ./test-feature-prepare && php vendor/phpunit/phpunit/phpunit --configuration phpunit.feature.xml.dist ./tests/FeatureTests",
     "test:example-generation-controller": "php bin/console cache:clear && ./test-feature-prepare && php vendor/phpunit/phpunit/phpunit --configuration phpunit.feature.xml.dist ./tests/ExampleGenerationController && php bin/console cache:clear",
+    "test:example-generation-controller:test": "php bin/console cache:clear && ./test-feature-prepare && php vendor/phpunit/phpunit/phpunit --configuration phpunit.feature.xml.dist ./tests/ExampleGenerationController --group test && php bin/console cache:clear",
     "test:example-generation-command": "php bin/console cache:clear && ./test-feature-command-prepare && php vendor/phpunit/phpunit/phpunit --configuration phpunit.feature.xml.dist ./tests/ExampleGenerationCommand && php bin/console cache:clear",
     "test:feature:test": "php bin/console cache:clear && ./test-feature-prepare && php vendor/phpunit/phpunit/phpunit --configuration phpunit.feature.xml.dist ./tests/FeatureTests --group test",
     "test:coverage:xml": "export XDEBUG_MODE=coverage && php ./vendor/phpunit/phpunit/phpunit --coverage-clover coverage.xml",

docs/api-endpoints/element/delete-element.md

@@ -21,7 +21,7 @@ curl \
 
 ### **🟢 Success 204**
 
-<div class="code-title">Response Headers</div>
+<div class="code-title auto-refresh">Response Headers</div>
 
 [Response Body](./delete-element/204-response-header.txt ':include :type=code')
 
@@ -31,11 +31,11 @@ Success response does not have a return body.
 
 This error can only be thrown if the token is invalid or if there is no default anonymous user.
 
-<div class="code-title">Response Headers</div>
+<div class="code-title auto-refresh">Response Headers</div>
 
 [Response Body](./delete-element/401-response-header.txt ':include :type=code')
 
-<div class="code-title">Response Body</div>
+<div class="code-title auto-refresh">Response Body</div>
 
 [Response Body](./delete-element/401-response-body.json ':include :type=code problem+json')
 
@@ -44,11 +44,11 @@ This error can only be thrown if the token is invalid or if there is no default
 Error 404 is thrown if the element to be deleted does not exist or if the user does not have permission to delete the
 element.
 
-<div class="code-title">Response Headers</div>
+<div class="code-title auto-refresh">Response Headers</div>
 
 [Response Body](./delete-element/404-response-header.txt ':include :type=code')
 
-<div class="code-title">Response Body</div>
+<div class="code-title auto-refresh">Response Body</div>
 
 [Response Body](./delete-element/404-response-body.json ':include :type=code problem+json')
 

docs/api-endpoints/element/delete-element/204-response-header.txt

@@ -1,9 +1,8 @@
-Access-Control-Allow-Origin: *
 Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
-Access-Control-Allow-Methods: GET, POST, OPTIONS, PUT, PATCH, DELETE
-Allow: GET, POST, OPTIONS, PUT, PATCH, DELETE
-Content-Type: application/json; charset=utf-8
+Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
+Access-Control-Allow-Origin: *
+Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
 Cache-Control: no-cache, private
-Date: Fri, 15 Sep 2023 08:03:41 GMT
+Date: Mon, 11 Dec 2023 12:11:20 GMT
 Server: Unit
-Transfer-Encoding: chunked
+X-Powered-By: Ember-Nexus-API

docs/api-endpoints/element/delete-element/401-response-body.json

@@ -1,6 +1,6 @@
 {
-  "type": "Invalid authorization token",
+  "type": "http://ember-nexus-api/error/401/unauthorized",
   "title": "Unauthorized",
-  "status": "401",
-  "detail": "Request requires authorization."
+  "status": 401,
+  "detail": "Authorization for the request failed due to possible problems with the token (incorrect or expired), password (incorrect or changed), the user's unique identifier, or the user's status (e.g., missing, blocked, or deleted)."
 }

docs/api-endpoints/element/delete-element/401-response-header.txt

@@ -1,9 +1,10 @@
-Access-Control-Allow-Origin: *
 Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
-Access-Control-Allow-Methods: GET, POST, OPTIONS, PUT, PATCH, DELETE
-Allow: GET, POST, OPTIONS, PUT, PATCH, DELETE
-Content-Type: application/json; charset=utf-8
+Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
+Access-Control-Allow-Origin: *
+Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
 Cache-Control: no-cache, private
-Date: Fri, 15 Sep 2023 08:03:41 GMT
+Content-Type: application/problem+json; charset=utf-8
+Date: Mon, 11 Dec 2023 12:11:20 GMT
 Server: Unit
-Transfer-Encoding: chunked
+Transfer-Encoding: chunked
+X-Powered-By: Ember-Nexus-API

docs/api-endpoints/element/delete-element/404-response-body.json

@@ -1,6 +1,6 @@
 {
-  "type": "404-not-found",
-  "title": "Not Found",
-  "status": "404",
-  "detail": "The requested resource was not found."
+  "type": "http://ember-nexus-api/error/404/not-found",
+  "title": "Not found",
+  "status": 404,
+  "detail": "Requested element was not found."
 }

docs/api-endpoints/element/delete-element/404-response-header.txt

@@ -1,9 +1,10 @@
-Access-Control-Allow-Origin: *
 Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
-Access-Control-Allow-Methods: GET, POST, OPTIONS, PUT, PATCH, DELETE
-Allow: GET, POST, OPTIONS, PUT, PATCH, DELETE
-Content-Type: application/json; charset=utf-8
+Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
+Access-Control-Allow-Origin: *
+Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
 Cache-Control: no-cache, private
-Date: Fri, 15 Sep 2023 08:03:41 GMT
+Content-Type: application/problem+json; charset=utf-8
+Date: Mon, 11 Dec 2023 12:12:52 GMT
 Server: Unit
-Transfer-Encoding: chunked
+Transfer-Encoding: chunked
+X-Powered-By: Ember-Nexus-API

docs/api-endpoints/user/delete-token.md

@@ -1,3 +1,127 @@
 # <span class="method-delete">DELETE</span>` /token -` Delete Token
 
+<!-- panels:start -->
+<!-- div:left-panel -->
+
 Deletes the currently used token.
+
+## Request Example
+
+```bash
+curl \
+  -X DELETE
+  -H "Authorization: Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc" \
+  https://api.localhost/token
+```
+
+<!-- tabs:start -->
+
+### **🟢 Success 204**
+
+<div class="code-title auto-refresh">Response Headers</div>
+
+[Response Body](./delete-token/204-response-header.txt ':include :type=code')
+
+Success response does not have a return body.
+
+### **🔴 Error 401**
+
+This error can only be thrown if the token is invalid or if there is no default anonymous user.
+
+<div class="code-title auto-refresh">Response Headers</div>
+
+[Response Body](./delete-token/401-response-header.txt ':include :type=code')
+
+<div class="code-title auto-refresh">Response Body</div>
+
+[Response Body](./delete-token/401-response-body.json ':include :type=code problem+json')
+
+### **🔴 Error 429**
+
+<div class="code-title">Response Headers</div>
+
+[Response Body](./delete-token/429-response-header.txt ':include :type=code')
+
+<div class="code-title">Response Body</div>
+
+[Response Body](./delete-token/429-response-body.json ':include :type=code problem+json')
+
+<!-- tabs:end -->
+
+<!-- div:right-panel -->
+
+## Internal Workflow
+
+Once the server receives such a request, it checks several things internally:
+
+<div id="graph-container-1" class="graph-container" style="height:1000px"></div>
+
+<!-- panels:end -->
+
+<script>
+G6.registerEdge('polyline-edge', {
+  draw(cfg, group) {
+    const { startPoint, endPoint } = cfg;
+    const hgap = Math.abs(endPoint.x - startPoint.x);
+
+    const path = [
+      ['M', startPoint.x, startPoint.y],
+      [
+        'C',
+        startPoint.x + hgap / 4,
+        startPoint.y,
+        endPoint.x - hgap / 2,
+        endPoint.y,
+        endPoint.x,
+        endPoint.y,
+      ],
+    ];
+    const shape = group.addShape('path', {
+      attrs: {
+        stroke: '#AAB7C4',
+        path,
+      },
+      name: 'path-shape',
+    });
+    const midPoint = {
+      x: (startPoint.x + endPoint.x) / 2,
+      y: (startPoint.y + endPoint.y) / 2,
+    };
+    const label = group.addShape('text', {
+      attrs: {
+        text: cfg.label + '###########',
+        x: midPoint.x,
+        y: midPoint.y,
+        textAlign: 'center',
+        textBaseline: 'middle',
+        fill: '#000',
+        fontSize: 14,
+      },
+      name: 'label-shape',
+    });
+    return shape;
+  },
+});
+renderWorkflow(document.getElementById('graph-container-1'), {
+  nodes: [
+    { id: 'init', ...workflowStart, label: 'server receives DELETE-request' },
+    { id: 'checkToken', ...workflowDecision, label: 'does request contain token?' },
+    { id: 'checkTokenValidity', ...workflowDecision, label: 'is token valid?' },
+    { id: 'checkRateLimit', ...workflowDecision, label: "does request exceed\nrate limit?" },
+    { id: 'deleteToken', ...workflowStep, label: 'delete token' },
+    { id: 'error401', ...workflowEndError, label: "return 401" },
+    { id: 'error429', ...workflowEndError, label: 'return 429' },
+    { id: 'success204', ...workflowEndSuccess , label: "return 204"},
+  ],
+  edges: [
+    { source: 'init', target: 'checkToken', label: '' },
+    { source: 'checkToken', target: 'checkTokenValidity', label: 'yes' },
+    { source: 'checkToken', target: 'error401', label: 'no' },
+    { source: 'checkTokenValidity', target: 'checkRateLimit', label: 'yes' },
+    { source: 'checkTokenValidity', target: 'error401', label: 'no' },
+    { source: 'checkRateLimit', target: 'deleteToken', label: 'no' },
+    { source: 'checkRateLimit', target: 'error429', label: 'yes' },
+    { source: 'deleteToken', target: 'success204' },
+  ],
+}, 'TB');
+</script>

docs/api-endpoints/user/delete-token/204-response-header.txt

@@ -0,0 +1,8 @@
+Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
+Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
+Access-Control-Allow-Origin: *
+Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
+Cache-Control: no-cache, private
+Date: Mon, 11 Dec 2023 12:05:26 GMT
+Server: Unit
+X-Powered-By: Ember-Nexus-API

docs/api-endpoints/user/delete-token/401-response-body.json

@@ -0,0 +1,6 @@
+{
+  "type": "http://ember-nexus-api/error/401/unauthorized",
+  "title": "Unauthorized",
+  "status": 401,
+  "detail": "Authorization for the request failed due to possible problems with the token (incorrect or expired), password (incorrect or changed), the user's unique identifier, or the user's status (e.g., missing, blocked, or deleted)."
+}

docs/api-endpoints/user/delete-token/401-response-header.txt

@@ -0,0 +1,10 @@
+Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
+Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
+Access-Control-Allow-Origin: *
+Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
+Cache-Control: no-cache, private
+Content-Type: application/problem+json; charset=utf-8
+Date: Mon, 11 Dec 2023 12:03:46 GMT
+Server: Unit
+Transfer-Encoding: chunked
+X-Powered-By: Ember-Nexus-API

docs/api-endpoints/user/delete-token/429-response-body.json

@@ -0,0 +1,6 @@
+{
+  "type": "429-too-many-requests",
+  "title": "Too Many Requests",
+  "status": "429",
+  "detail": "The client sent too many requests in a given timeframe; rate limiting is active."
+}

docs/api-endpoints/user/delete-token/429-response-header.txt

@@ -0,0 +1,9 @@
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
+Access-Control-Allow-Methods: GET, POST, OPTIONS, PUT, PATCH, DELETE
+Allow: GET, POST, OPTIONS, PUT, PATCH, DELETE
+Content-Type: application/json; charset=utf-8
+Cache-Control: no-cache, private
+Date: Fri, 15 Sep 2023 08:03:41 GMT
+Server: Unit
+Transfer-Encoding: chunked

tests/ExampleGenerationController/Element/DeleteElementTest.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\tests\ExampleGenerationController\Element;
+
+use App\Tests\ExampleGenerationController\BaseRequestTestCase;
+
+class DeleteElementTest extends BaseRequestTestCase
+{
+    private const PATH_TO_ROOT = __DIR__.'/../../../';
+
+    private const TOKEN = 'secret-token:CevJS3ZkDtJcCdqEhFKqWF';
+    private const ELEMENT = '55cce573-1377-4781-be16-8b81587aca10';
+    private const NON_EXISTENT_ELEMENT = '00000000-0000-4000-8000-000000000000';
+
+    public function testDeleteElementSuccess(): void
+    {
+        $response = $this->runDeleteRequest(sprintf('/%s', self::ELEMENT), self::TOKEN);
+        $this->assertNoContentResponse($response);
+        $documentationHeadersPath = 'docs/api-endpoints/element/delete-element/204-response-header.txt';
+        $this->assertHeadersInDocumentationAreIdenticalToHeadersFromRequest(
+            self::PATH_TO_ROOT,
+            $documentationHeadersPath,
+            $response
+        );
+    }
+
+    public function testDeleteElementFailure401(): void
+    {
+        $response = $this->runDeleteRequest(sprintf('/%s', self::ELEMENT), 'tokenDoesNotExist');
+        $this->assertIsProblemResponse($response, 401);
+        $documentationHeadersPath = 'docs/api-endpoints/element/delete-element/401-response-header.txt';
+        $documentationBodyPath = 'docs/api-endpoints/element/delete-element/401-response-body.json';
+        $this->assertHeadersInDocumentationAreIdenticalToHeadersFromRequest(
+            self::PATH_TO_ROOT,
+            $documentationHeadersPath,
+            $response
+        );
+        $this->assertBodyInDocumentationIsIdenticalToBodyFromRequest(
+            self::PATH_TO_ROOT,
+            $documentationBodyPath,
+            $response
+        );
+    }
+
+    public function testDeleteElementFailure404(): void
+    {
+        $response = $this->runDeleteRequest(sprintf('/%s', self::NON_EXISTENT_ELEMENT), self::TOKEN);
+        $this->assertIsProblemResponse($response, 404);
+        $documentationHeadersPath = 'docs/api-endpoints/element/delete-element/404-response-header.txt';
+        $documentationBodyPath = 'docs/api-endpoints/element/delete-element/404-response-body.json';
+        $this->assertHeadersInDocumentationAreIdenticalToHeadersFromRequest(
+            self::PATH_TO_ROOT,
+            $documentationHeadersPath,
+            $response
+        );
+        $this->assertBodyInDocumentationIsIdenticalToBodyFromRequest(
+            self::PATH_TO_ROOT,
+            $documentationBodyPath,
+            $response
+        );
+    }
+}