added basic api docs variables for the three methods of API versioning.

rupadana · Aug 18, 2024 · fea4cf3 · fea4cf3
1 parent a2d57ed
commit fea4cf3
Show file tree

Hide file tree

Showing 5 changed files with 322 additions and 18 deletions.
diff --git a/stubs/Api/CreateHandler.stub b/stubs/Api/CreateHandler.stub
@@ -16,6 +16,36 @@ $hasTenancy = $panel->hasTenancy();
 $tenantSlugAttribute = $panel->getTenantSlugAttribute();
 $panelPrefix = app(ApiService::class)->isRoutePrefixedByPanel() ? $panelPath ?? $panelId : '';
 
+defined("API_DEFAULT_TRANSFORMER_NAME") ?: define("API_DEFAULT_TRANSFORMER_NAME", config('api-service.route.default_transformer_name'));
+defined("API_VERSION_PARAMETER_NAME") ?: define("API_VERSION_PARAMETER_NAME", config('api-service.route.api_version_parameter_name'));
+defined("API_TRANSFORMER_HEADER") ?: define("API_TRANSFORMER_HEADER", config('api-service.route.api_transformer_header'));
+
+function apiVersionPath() {
+    defined("API_VERSION_URL_PATH") ?: define("API_VERSION_URL_PATH", '{version}/');
+}
+
+function apiVersionQuery() {
+    defined("API_VERSION_URL_QUERY") ?: define("API_VERSION_URL_QUERY", true);
+}
+
+function apiVersionHeaders() {
+    defined("API_VERSION_URL_HEADERS") ?: define("API_VERSION_URL_HEADERS", true);
+}
+
+function apiVersionDefault() {
+    defined("API_VERSION_URL_PATH") ?: define("API_VERSION_URL_PATH", '');
+    defined("API_VERSION_URL_QUERY") ?: define("API_VERSION_URL_QUERY", false);
+    defined("API_VERSION_URL_HEADERS") ?: define("API_VERSION_URL_HEADERS", false);
+}
+
+match (config('api-service.route.api_version_method')) {
+    'path' => apiVersionPath(),
+    'query' => apiVersionQuery(),
+    'headers' => apiVersionHeaders(),
+    default => apiVersionDefault(),
+};
+
+
 if (
     ApiService::isTenancyEnabled() &&
     ApiService::tenancyAwareness() &&
@@ -49,7 +79,7 @@ defined("BASE_URL") ?: define("BASE_URL", config('app.url'));
         (TENANT_AWARENESS_{{ capitalsResource }}) ?
             new OAT\Server(
                 description: "API Server Filament Panel",
-                url: BASE_URL . "/api/{panel}" . PANEL_PREFIX_{{ capitalsResource }}_CREATE . "/{tenant}",
+                url: BASE_URL . "/api/" . API_VERSION_URL_PATH . "{panel}" . PANEL_PREFIX_{{ capitalsResource }}_CREATE . "/{tenant}",
                 variables: [
                     new OAT\ServerVariable(
                         serverVariable: "panel",
@@ -63,16 +93,48 @@ defined("BASE_URL") ?: define("BASE_URL", config('app.url'));
                         default: ""
                     ),
 
-                ]
+                (API_VERSION_URL_PATH != '') ?
+                    new OAT\ServerVariable(
+                        serverVariable: "version",
+                        description: 'Version or Transformer name of this API endpoint',
+                        default: API_DEFAULT_TRANSFORMER_NAME,
+                    ),
+                : null,
+            ]
             ) :
             new OAT\Server(
                 description: "API Server Filament Panel",
-                url: BASE_URL . "/api/" . PANEL_PREFIX_{{ capitalsResource }}_CREATE . "/",
+                url: BASE_URL . "/api/" . API_VERSION_URL_PATH . PANEL_PREFIX_{{ capitalsResource }}_CREATE . "/",
+                variables: [
+                (API_VERSION_URL_PATH != '') ?
+                    new OAT\ServerVariable(
+                        serverVariable: "version",
+                        description: 'Version or Transformer name of this API endpoint',
+                        default: API_DEFAULT_TRANSFORMER_NAME,
+                    ),
+                : null,
+                ]
             )
     ],
     security: (!RESOURCE_PUBLIC_{{ capitalsResource }}_CREATE) ?  [["bearerAuth" => []]] : null,
     parameters: [
         // (TENANT_AWARENESS_{{ capitalsResource }}) ? new OAT\Parameter(ref: "#/components/parameters/tenant") : null,
+
+        (API_VERSION_URL_QUERY) ? new OAT\Parameter(
+            name: API_VERSION_PARAMETER_NAME,
+            in: "query",
+            required: true,
+            description: "Set the correct API Version / Transformer you want to use.",
+            schema: new OAT\Schema(type: "string")
+        ) : null,
+
+        (API_VERSION_URL_HEADERS) ? new OAT\Parameter(
+            name: API_TRANSFORMER_HEADER,
+            in: "header",
+            required: true,
+            description: "Set the correct API Version / Transformer you want to use.",
+            schema: new OAT\Schema(type: "string")
+        ) : null,
     ],
     requestBody: new OAT\RequestBody(
         required: true,

diff --git a/stubs/Api/DeleteHandler.stub b/stubs/Api/DeleteHandler.stub
@@ -16,6 +16,35 @@ $hasTenancy = $panel->hasTenancy();
 $tenantSlugAttribute = $panel->getTenantSlugAttribute();
 $panelPrefix = app(ApiService::class)->isRoutePrefixedByPanel() ? $panelPath ?? $panelId : '';
 
+defined("API_DEFAULT_TRANSFORMER_NAME") ?: define("API_DEFAULT_TRANSFORMER_NAME", config('api-service.route.default_transformer_name'));
+defined("API_VERSION_PARAMETER_NAME") ?: define("API_VERSION_PARAMETER_NAME", config('api-service.route.api_version_parameter_name'));
+defined("API_TRANSFORMER_HEADER") ?: define("API_TRANSFORMER_HEADER", config('api-service.route.api_transformer_header'));
+
+function apiVersionPath() {
+    defined("API_VERSION_URL_PATH") ?: define("API_VERSION_URL_PATH", '{version}/');
+}
+
+function apiVersionQuery() {
+    defined("API_VERSION_URL_QUERY") ?: define("API_VERSION_URL_QUERY", true);
+}
+
+function apiVersionHeaders() {
+    defined("API_VERSION_URL_HEADERS") ?: define("API_VERSION_URL_HEADERS", true);
+}
+
+function apiVersionDefault() {
+    defined("API_VERSION_URL_PATH") ?: define("API_VERSION_URL_PATH", '');
+    defined("API_VERSION_URL_QUERY") ?: define("API_VERSION_URL_QUERY", false);
+    defined("API_VERSION_URL_HEADERS") ?: define("API_VERSION_URL_HEADERS", false);
+}
+
+match (config('api-service.route.api_version_method')) {
+    'path' => apiVersionPath(),
+    'query' => apiVersionQuery(),
+    'headers' => apiVersionHeaders(),
+    default => apiVersionDefault(),
+};
+
 if (
     ApiService::isTenancyEnabled() &&
     ApiService::tenancyAwareness() &&
@@ -49,7 +78,7 @@ defined("BASE_URL") ?: define("BASE_URL", config('app.url'));
         (TENANT_AWARENESS_{{ capitalsResource }}) ?
             new OAT\Server(
                 description: "API Server Filament Panel",
-                url: BASE_URL . "/api/{panel}" . PANEL_PREFIX_{{ capitalsResource }}_DELETE . "/{tenant}",
+                url: BASE_URL . "/api/" . API_VERSION_URL_PATH . "{panel}" . PANEL_PREFIX_{{ capitalsResource }}_DELETE . "/{tenant}",
                 variables: [
                     new OAT\ServerVariable(
                         serverVariable: "panel",
@@ -62,11 +91,27 @@ defined("BASE_URL") ?: define("BASE_URL", config('app.url'));
                         description: 'ID of the tenant',
                         default: ""
                     ),
-                ]
+                (API_VERSION_URL_PATH != '') ?
+                    new OAT\ServerVariable(
+                        serverVariable: "version",
+                        description: 'Version or Transformer name of this API endpoint',
+                        default: API_DEFAULT_TRANSFORMER_NAME,
+                    ),
+                : null,
+            ]
             ) :
             new OAT\Server(
                 description: "API Server Filament Panel",
-                url: BASE_URL . "/api/" . PANEL_PREFIX_{{ capitalsResource }}_DELETE . "/",
+                url: BASE_URL . "/api/" . API_VERSION_URL_PATH . PANEL_PREFIX_{{ capitalsResource }}_DELETE . "/",
+                variables: [
+                (API_VERSION_URL_PATH != '') ?
+                    new OAT\ServerVariable(
+                        serverVariable: "version",
+                        description: 'Version or Transformer name of this API endpoint',
+                        default: API_DEFAULT_TRANSFORMER_NAME,
+                    ),
+                : null,
+                ]
             )
     ],
     security: (!RESOURCE_PUBLIC_{{ capitalsResource }}_DELETE) ?  [["bearerAuth" => []]] : null,
@@ -80,6 +125,21 @@ defined("BASE_URL") ?: define("BASE_URL", config('app.url'));
             schema: new OAT\Schema(type: "integer"),
             example: "", // OAT\Examples(example="int", value="0", summary="An int value."),
         ),
+        (API_VERSION_URL_QUERY) ? new OAT\Parameter(
+            name: API_VERSION_PARAMETER_NAME,
+            in: "query",
+            required: true,
+            description: "Set the correct API Version / Transformer you want to use.",
+            schema: new OAT\Schema(type: "string")
+        ) : null,
+
+        (API_VERSION_URL_HEADERS) ? new OAT\Parameter(
+            name: API_TRANSFORMER_HEADER,
+            in: "header",
+            required: true,
+            description: "Set the correct API Version / Transformer you want to use.",
+            schema: new OAT\Schema(type: "string")
+        ) : null,
     ],
     responses: [
         new OAT\Response(response: 200, description: 'Operation succesful', content: new OAT\JsonContent(type: "object", properties: [

diff --git a/stubs/Api/DetailHandler.stub b/stubs/Api/DetailHandler.stub
@@ -16,6 +16,36 @@ $hasTenancy = $panel->hasTenancy();
 $tenantSlugAttribute = $panel->getTenantSlugAttribute();
 $panelPrefix = app(ApiService::class)->isRoutePrefixedByPanel() ? $panelPath ?? $panelId : '';
 
+defined("API_DEFAULT_TRANSFORMER_NAME") ?: define("API_DEFAULT_TRANSFORMER_NAME", config('api-service.route.default_transformer_name'));
+defined("API_VERSION_PARAMETER_NAME") ?: define("API_VERSION_PARAMETER_NAME", config('api-service.route.api_version_parameter_name'));
+defined("API_TRANSFORMER_HEADER") ?: define("API_TRANSFORMER_HEADER", config('api-service.route.api_transformer_header'));
+
+function apiVersionPath() {
+    defined("API_VERSION_URL_PATH") ?: define("API_VERSION_URL_PATH", '{version}/');
+}
+
+function apiVersionQuery() {
+    defined("API_VERSION_URL_QUERY") ?: define("API_VERSION_URL_QUERY", true);
+}
+
+function apiVersionHeaders() {
+    defined("API_VERSION_URL_HEADERS") ?: define("API_VERSION_URL_HEADERS", true);
+}
+
+function apiVersionDefault() {
+    defined("API_VERSION_URL_PATH") ?: define("API_VERSION_URL_PATH", '');
+    defined("API_VERSION_URL_QUERY") ?: define("API_VERSION_URL_QUERY", false);
+    defined("API_VERSION_URL_HEADERS") ?: define("API_VERSION_URL_HEADERS", false);
+}
+
+match (config('api-service.route.api_version_method')) {
+    'path' => apiVersionPath(),
+    'query' => apiVersionQuery(),
+    'headers' => apiVersionHeaders(),
+    default => apiVersionDefault(),
+};
+
+
 if (
     ApiService::isTenancyEnabled() &&
     ApiService::tenancyAwareness() &&
@@ -59,7 +89,7 @@ defined("BASE_URL") ?: define("BASE_URL", config('app.url'));
         (TENANT_AWARENESS_{{ capitalsResource }}) ?
             new OAT\Server(
                 description: "API Server Filament Panel",
-                url: BASE_URL . "/api/{panel}" . PANEL_PREFIX_{{ capitalsResource }}_DETAIL . "/{tenant}",
+                url: BASE_URL . "/api/" . API_VERSION_URL_PATH . "{panel}" . PANEL_PREFIX_{{ capitalsResource }}_DETAIL . "/{tenant}",
                 variables: [
                     new OAT\ServerVariable(
                         serverVariable: "panel",
@@ -72,12 +102,27 @@ defined("BASE_URL") ?: define("BASE_URL", config('app.url'));
                         description: 'ID of the tenant',
                         default: ""
                     ),
-
-                ]
+                (API_VERSION_URL_PATH != '') ?
+                    new OAT\ServerVariable(
+                        serverVariable: "version",
+                        description: 'Version or Transformer name of this API endpoint',
+                        default: API_DEFAULT_TRANSFORMER_NAME,
+                    ),
+                : null,
+            ]
             ) :
             new OAT\Server(
                 description: "API Server Filament Panel",
-                url: BASE_URL . "/api/" . PANEL_PREFIX_{{ capitalsResource }}_DETAIL . "/",
+                url: BASE_URL . "/api/" . API_VERSION_URL_PATH . PANEL_PREFIX_{{ capitalsResource }}_DETAIL . "/",
+                variables: [
+                (API_VERSION_URL_PATH != '') ?
+                    new OAT\ServerVariable(
+                        serverVariable: "version",
+                        description: 'Version or Transformer name of this API endpoint',
+                        default: API_DEFAULT_TRANSFORMER_NAME,
+                    ),
+                : null,
+                ]
             )
     ],
     security: (!RESOURCE_PUBLIC_{{ capitalsResource }}_DETAIL) ?  [["bearerAuth" => []]] : null,
@@ -93,6 +138,22 @@ defined("BASE_URL") ?: define("BASE_URL", config('app.url'));
 
         // (TENANT_AWARENESS_{{ capitalsResource }}) ? new OAT\Parameter(ref: "#/components/parameters/tenant") : null,
 
+        (API_VERSION_URL_QUERY) ? new OAT\Parameter(
+            name: API_VERSION_PARAMETER_NAME,
+            in: "query",
+            required: true,
+            description: "Set the correct API Version / Transformer you want to use.",
+            schema: new OAT\Schema(type: "string")
+        ) : null,
+
+        (API_VERSION_URL_HEADERS) ? new OAT\Parameter(
+            name: API_TRANSFORMER_HEADER,
+            in: "header",
+            required: true,
+            description: "Set the correct API Version / Transformer you want to use.",
+            schema: new OAT\Schema(type: "string")
+        ) : null,
+
         new OAT\Parameter(
             name: "id",
             description: "{{ modelClass }} ID",

diff --git a/stubs/Api/PaginationHandler.stub b/stubs/Api/PaginationHandler.stub
@@ -17,6 +17,35 @@ $hasTenancy = $panel->hasTenancy();
 $tenantSlugAttribute = $panel->getTenantSlugAttribute();
 $panelPrefix = app(ApiService::class)->isRoutePrefixedByPanel() ? $panelPath ?? $panelId : '';
 
+defined("API_DEFAULT_TRANSFORMER_NAME") ?: define("API_DEFAULT_TRANSFORMER_NAME", config('api-service.route.default_transformer_name'));
+defined("API_VERSION_PARAMETER_NAME") ?: define("API_VERSION_PARAMETER_NAME", config('api-service.route.api_version_parameter_name'));
+defined("API_TRANSFORMER_HEADER") ?: define("API_TRANSFORMER_HEADER", config('api-service.route.api_transformer_header'));
+
+function apiVersionPath() {
+    defined("API_VERSION_URL_PATH") ?: define("API_VERSION_URL_PATH", '{version}/');
+}
+
+function apiVersionQuery() {
+    defined("API_VERSION_URL_QUERY") ?: define("API_VERSION_URL_QUERY", true);
+}
+
+function apiVersionHeaders() {
+    defined("API_VERSION_URL_HEADERS") ?: define("API_VERSION_URL_HEADERS", true);
+}
+
+function apiVersionDefault() {
+    defined("API_VERSION_URL_PATH") ?: define("API_VERSION_URL_PATH", '');
+    defined("API_VERSION_URL_QUERY") ?: define("API_VERSION_URL_QUERY", false);
+    defined("API_VERSION_URL_HEADERS") ?: define("API_VERSION_URL_HEADERS", false);
+}
+
+match (config('api-service.route.api_version_method')) {
+    'path' => apiVersionPath(),
+    'query' => apiVersionQuery(),
+    'headers' => apiVersionHeaders(),
+    default => apiVersionDefault(),
+};
+
 if (
     ApiService::isTenancyEnabled() &&
     ApiService::tenancyAwareness() &&
@@ -59,7 +88,7 @@ defined("BASE_URL") ?: define("BASE_URL", config('app.url'));
         (TENANT_AWARENESS_{{ capitalsResource }}) ?
             new OAT\Server(
                 description: "API Server Filament Panel",
-                url: BASE_URL . "/api/{panel}" . PANEL_PREFIX_{{ capitalsResource }}_PAGINATION . "/{tenant}",
+                url: BASE_URL . "/api/" . API_VERSION_URL_PATH . "{panel}" . PANEL_PREFIX_{{ capitalsResource }}_PAGINATION . "/{tenant}",
                 variables: [
                     new OAT\ServerVariable(
                         serverVariable: "panel",
@@ -72,12 +101,27 @@ defined("BASE_URL") ?: define("BASE_URL", config('app.url'));
                         description: 'ID of the tenant',
                         default: ""
                     ),
-
-                ]
+                (API_VERSION_URL_PATH != '') ?
+                    new OAT\ServerVariable(
+                        serverVariable: "version",
+                        description: 'Version or Transformer name of this API endpoint',
+                        default: API_DEFAULT_TRANSFORMER_NAME,
+                    ),
+                : null,
+            ]
             ) :
             new OAT\Server(
                 description: "API Server Filament Panel",
-                url: BASE_URL . "/api/" . PANEL_PREFIX_{{ capitalsResource }}_PAGINATION . "/",
+                url: BASE_URL . "/api/" . API_VERSION_URL_PATH . API_VERSION_URL_PATH . PANEL_PREFIX_{{ capitalsResource }}_PAGINATION . "/",
+                variables: [
+                (API_VERSION_URL_PATH != '') ?
+                    new OAT\ServerVariable(
+                        serverVariable: "version",
+                        description: 'Version or Transformer name of this API endpoint',
+                        default: API_DEFAULT_TRANSFORMER_NAME,
+                    ),
+                : null,
+                ]
             )
     ],
     summary: "Get list of {{ pluralClass }}",
@@ -96,6 +140,22 @@ defined("BASE_URL") ?: define("BASE_URL", config('app.url'));
         // (TENANT_AWARENESS_{{ capitalsResource }}) ? new OAT\Parameter(ref: "#/components/parameters/tenant") : null,
         // (TENANT_AWARENESS_{{ capitalsResource }}) ? new OAT\Parameter(name: "tenant", description: 'ID of the tenant', schema: new OAT\Schema(type: 'integer|string'), required: true, in: "path") : null,
 
+        (API_VERSION_URL_QUERY) ? new OAT\Parameter(
+            name: API_VERSION_PARAMETER_NAME,
+            in: "query",
+            required: true,
+            description: "Set the correct API Version / Transformer you want to use.",
+            schema: new OAT\Schema(type: "string")
+        ) : null,
+
+        (API_VERSION_URL_HEADERS) ? new OAT\Parameter(
+            name: API_TRANSFORMER_HEADER,
+            in: "header",
+            required: true,
+            description: "Set the correct API Version / Transformer you want to use.",
+            schema: new OAT\Schema(type: "string")
+        ) : null,
+
         new OAT\Parameter(
             name: "page[offset]",
             description: "Pagination offset option",