Merge pull request #270 from hafijul233/master

Open API 3 Path Parameter & Delete Standard Rule Check Failed Issue Fixed

Author: kevincobain2000

config/request-docs.php

@@ -64,7 +64,11 @@
         'license' => 'Apache 2.0',
         'license_url' => 'https://www.apache.org/licenses/LICENSE-2.0.html',
         'server_url' => env('APP_URL', 'http://localhost'),
-
+        //openapi 3.0.x doesn't support request body for delete operation
+        //ref: https://github.com/OAI/OpenAPI-Specification/pull/2117
+        'delete_with_body' => false,
+        //exclude http methods that will be excluded from openapi export
+        'exclude_http_methods' => [],
         // for now putting default responses for all. This can be changed later based on specific needs
         'responses' => [
             '200' => [

src/LaravelRequestDocs.php

@@ -47,7 +47,7 @@ public function getDocs(
             Request::METHOD_PATCH  => $showPatch,
             Request::METHOD_DELETE => $showDelete,
             Request::METHOD_HEAD   => $showHead,
-        ], fn(bool $shouldShow) => $shouldShow);
+        ], fn (bool $shouldShow) => $shouldShow);
 
         /** @var string[] $methods */
         $methods = array_keys($filteredMethods);
@@ -402,7 +402,7 @@ private function customParamsDocComment(string $docComment): array
             $comments = $this->multiExplode([' ', '|'], $comment);
 
             if (count($comments) > 0) {
-                $params[$comments[0]] = array_values(array_filter($comments, fn($item) => $item !== $comments[0]));
+                $params[$comments[0]] = array_values(array_filter($comments, fn ($item) => $item !== $comments[0]));
             }
         }
 

src/LaravelRequestDocsServiceProvider.php

@@ -20,7 +20,7 @@ public function configurePackage(Package $package): void
             ->hasConfigFile('request-docs')
             // ->hasAssets()
             ->hasViews();
-            // ->hasAssets();
+        // ->hasAssets();
         // publish resources/dist/_astro to public/
         $this->publishes([
             __DIR__.'/../resources/dist/_astro' => public_path('request-docs/_astro'),

src/LaravelRequestDocsToOpenApi.php

@@ -33,9 +33,18 @@ public function openApi(array $docs): LaravelRequestDocsToOpenApi
     private function docsToOpenApi(array $docs): void
     {
         $this->openApi['paths'] = [];
+        $deleteWithBody   = config('request-docs.open_api.delete_with_body', false);
+        $excludeHttpMethods     = array_map(fn ($item) => strtolower($item), config('request-docs.open_api.exclude_http_methods', []));
+
         foreach ($docs as $doc) {
-            $requestHasFile  = false;
+
             $httpMethod      = strtolower($doc->getHttpMethod());
+
+            if (in_array($httpMethod, $excludeHttpMethods)) {
+                continue;
+            }
+
+            $requestHasFile  = false;
             $isGet           = $httpMethod == 'get';
             $isPost          = $httpMethod == 'post';
             $isPut           = $httpMethod == 'put';
@@ -46,7 +55,7 @@ private function docsToOpenApi(array $docs): void
             $this->openApi['paths'][$uriLeadingSlash][$httpMethod]['parameters']  = [];
 
             foreach ($doc->getPathParameters() as $parameter => $rule) {
-                $this->openApi['paths'][$uriLeadingSlash][$httpMethod]['parameters'][] = $this->makeQueryParameterItem($parameter, $rule);
+                $this->openApi['paths'][$uriLeadingSlash][$httpMethod]['parameters'][] = $this->makePathParameterItem($parameter, $rule);
             }
 
             $this->openApi['paths'][$uriLeadingSlash][$httpMethod]['responses'] = config('request-docs.open_api.responses', []);
@@ -65,7 +74,7 @@ private function docsToOpenApi(array $docs): void
 
             $contentType = $requestHasFile ? 'multipart/form-data' : 'application/json';
 
-            if ($isPost || $isPut || $isDelete) {
+            if ($isPost || $isPut || ($isDelete && $deleteWithBody)) {
                 $this->openApi['paths'][$uriLeadingSlash][$httpMethod]['requestBody'] = $this->makeRequestBodyItem($contentType);
             }
 
@@ -75,7 +84,7 @@ private function docsToOpenApi(array $docs): void
                         $parameter                                                             = $this->makeQueryParameterItem($attribute, $rule);
                         $this->openApi['paths'][$uriLeadingSlash][$httpMethod]['parameters'][] = $parameter;
                     }
-                    if ($isPost || $isPut || $isDelete) {
+                    if ($isPost || $isPut || ($isDelete && $deleteWithBody)) {
                         $this->openApi['paths'][$uriLeadingSlash][$httpMethod]['requestBody']['content'][$contentType]['schema']['properties'][$attribute] = $this->makeRequestBodyContentPropertyItem($rule);
                     }
                 }
@@ -106,6 +115,25 @@ protected function makeQueryParameterItem(string $attribute, $rule): array
         return $parameter;
     }
 
+    protected function makePathParameterItem(string $attribute, $rule): array
+    {
+        if (is_array($rule)) {
+            $rule = implode('|', $rule);
+        }
+
+        $parameter = [
+            'name'        => $attribute,
+            'description' => $rule,
+            'in'          => 'path',
+            'style'       => 'simple',
+            'required'    => str_contains($rule, 'required'),
+            'schema'      => [
+                'type' => $this->getAttributeType($rule),
+            ],
+        ];
+        return $parameter;
+    }
+
     protected function makeRequestBodyItem(string $contentType): array
     {
         $requestBody = [