Improve processor reference (zircote#1617)

DerManoMann · Jul 2, 2024 · 2382217 · 2382217
1 parent b308ec0
commit 2382217
Show file tree

Hide file tree

Showing 9 changed files with 64 additions and 18 deletions.
diff --git a/docs/reference/processors.md b/docs/reference/processors.md
@@ -7,7 +7,7 @@ For improvements head over to [GitHub](https://github.com/zircote/swagger-php) a
 
 *Processors are listed in the default order of execution.*
 
-## Processors
+## Default Processors
 ### [DocBlockDescriptions](https://github.com/zircote/swagger-php/tree/master/src/Processors/DocBlockDescriptions.php)
 
 Checks if the annotation has a summary and/or description property
@@ -58,11 +58,12 @@ Use the property context to extract useful information and inject that into the
 Build the openapi->paths using the detected `@OA\PathItem` and `@OA\Operation` (`@OA\Get`, `@OA\Post`, etc).
 ### [AugmentParameters](https://github.com/zircote/swagger-php/tree/master/src/Processors/AugmentParameters.php)
 
-
-### Config settings
+Augments shared and operations parameters from docblock comments.
+#### Config settings
 <dl>
   <dt><strong>augmentParameters.augmentOperationParameters</strong> : <span style="font-family: monospace;">bool</span></dt>
-  <dd><p>No details available.</p>  </dd>
+  <dt><strong>default</strong> :  : <span style="font-family: monospace;">true</span></dt>
+  <dd><p>If set to <code>true</code> try to find operation parameter descriptions in the operation docblock.</p>  </dd>
 </dl>
 
 
@@ -78,16 +79,47 @@ Split XmlContent into Schema and MediaType.
 ### [OperationId](https://github.com/zircote/swagger-php/tree/master/src/Processors/OperationId.php)
 
 Generate the OperationId based on the context of the OpenApi annotation.
-### Config settings
+#### Config settings
 <dl>
   <dt><strong>operationId.hash</strong> : <span style="font-family: monospace;">bool</span></dt>
-  <dd><p>No details available.</p>  </dd>
+  <dt><strong>default</strong> :  : <span style="font-family: monospace;">true</span></dt>
+  <dd><p>If set to <code>true</code> generate ids (md5) instead of clear text operation ids.</p>  </dd>
 </dl>
 
 
+### [AugmentTags](https://github.com/zircote/swagger-php/tree/master/src/Processors/AugmentTags.php)
+
+Ensures that all tags used on operations also exist in the global <code>tags</code> list.
 ### [CleanUnmerged](https://github.com/zircote/swagger-php/tree/master/src/Processors/CleanUnmerged.php)
 
 
+### [PathFilter](https://github.com/zircote/swagger-php/tree/master/src/Processors/PathFilter.php)
+
+Allows to filter endpoints based on tags and/or path.
+
+If no `tags` or `paths` filters are set, no filtering is performed.
+All filter (regular) expressions must be enclosed within delimiter characters as they are used as-is.
+#### Config settings
+<dl>
+  <dt><strong>pathFilter.tags</strong> : <span style="font-family: monospace;">array</span></dt>
+  <dt><strong>default</strong> :  : <span style="font-family: monospace;">[]</span></dt>
+  <dd><p>A list of regular expressions to match <code>tags</code> to include.</p>  </dd>
+</dl>
+<dl>
+  <dt><strong>pathFilter.paths</strong> : <span style="font-family: monospace;">array</span></dt>
+  <dt><strong>default</strong> :  : <span style="font-family: monospace;">[]</span></dt>
+  <dd><p>A list of regular expressions to match <code>paths</code> to include.</p>  </dd>
+</dl>
+
+
 ### [CleanUnusedComponents](https://github.com/zircote/swagger-php/tree/master/src/Processors/CleanUnusedComponents.php)
 
+Tracks the use of all <code>Components</code> and removed unused schemas.
+#### Config settings
+<dl>
+  <dt><strong>cleanUnusedComponents.enabled</strong> : <span style="font-family: monospace;">bool</span></dt>
+  <dt><strong>default</strong> :  : <span style="font-family: monospace;">false</span></dt>
+  <dd><p>Enables/disables the <code>CleanUnusedComponents</code> processor.</p>  </dd>
+</dl>
+
 
diff --git a/src/Processors/AugmentParameters.php b/src/Processors/AugmentParameters.php
@@ -11,11 +11,14 @@
 use OpenApi\Generator;
 use OpenApi\Processors\Concerns\DocblockTrait;
 
+/**
+ * Augments shared and operations parameters from docblock comments.
+ */
 class AugmentParameters implements ProcessorInterface
 {
     use DocblockTrait;
 
-    protected $augmentOperationParameters;
+    protected $augmentOperationParameters = true;
 
     public function __construct(bool $augmentOperationParameters = true)
     {

diff --git a/src/Processors/CleanUnusedComponents.php b/src/Processors/CleanUnusedComponents.php
@@ -17,9 +17,6 @@ class CleanUnusedComponents implements ProcessorInterface
 {
     use Concerns\AnnotationTrait;
 
-    /**
-     * @var bool
-     */
     protected $enabled = false;
 
     public function __construct(bool $enabled = false)
@@ -32,6 +29,9 @@ public function isEnabled(): bool
         return $this->enabled;
     }
 
+    /**
+     * Enables/disables the <code>CleanUnusedComponents</code> processor.
+     */
     public function setEnabled(bool $enabled): CleanUnusedComponents
     {
         $this->enabled = $enabled;

diff --git a/src/Processors/OperationId.php b/src/Processors/OperationId.php
@@ -15,7 +15,7 @@
  */
 class OperationId implements ProcessorInterface
 {
-    protected $hash;
+    protected $hash = true;
 
     public function __construct(bool $hash = true)
     {

diff --git a/src/Processors/PathFilter.php b/src/Processors/PathFilter.php
@@ -20,10 +20,8 @@ class PathFilter implements ProcessorInterface
 {
     use AnnotationTrait;
 
-    /** @var array */
     protected $tags = [];
 
-    /** @var array */
     protected $paths = [];
 
     public function __construct(array $tags = [], array $paths = [])

diff --git a/tools/procgen.php b/tools/procgen.php
@@ -9,6 +9,7 @@
 ob_start();
 
 echo $procgen->preamble('Processors');
+echo PHP_EOL . '## Default Processors' . PHP_EOL;
 
 foreach ($procgen->getProcessorsDetails() as $ii => $details) {
     $off = $ii + 1;
@@ -17,12 +18,15 @@
 
     if ($details['options']) {
         $configPrefix = lcfirst($details['name']) . '.';
-        echo '### Config settings' . PHP_EOL;
+        echo '#### Config settings' . PHP_EOL;
         foreach ($details['options'] as $name => $odetails) {
             if ($odetails) {
                 $var = ' : <span style="font-family: monospace;">' . $odetails['type'] . '</span>';
+                $default = ' : <span style="font-family: monospace;">' . $odetails['default'] . '</span>';
+
                 echo '<dl>' . PHP_EOL;
                 echo '  <dt><strong>' . $configPrefix . $name . '</strong>' . $var . '</dt>' . PHP_EOL;
+                echo '  <dt><strong>default</strong> : ' . $default . '</dt>' . PHP_EOL;
                 echo '  <dd>';
                 echo '<p>' . nl2br($odetails['phpdoc'] ? $odetails['phpdoc']['content'] : ProcGenerator::NO_DETAILS_AVAILABLE) . '</p>';
                 echo '  </dd>' . PHP_EOL;

diff --git a/tools/refgen.php b/tools/refgen.php
@@ -10,6 +10,7 @@
     ob_start();
 
     echo $refgen->preamble($type);
+    echo PHP_EOL . "## $type" . PHP_EOL;
 
     foreach ($refgen->classesForType($type) as $name => $details) {
         echo $refgen->formatClassHeader($name, $type);

diff --git a/tools/src/Docs/DocGenerator.php b/tools/src/Docs/DocGenerator.php
@@ -53,8 +53,6 @@ public function preamble(string $type): string
 
         $preamble .= <<< EOT
 
-## $type
-
 EOT;
 
         return $preamble;

diff --git a/tools/src/Docs/ProcGenerator.php b/tools/src/Docs/ProcGenerator.php
@@ -30,15 +30,25 @@ protected function getOptionsDetails(\ReflectionClass $rc): array
                 }
 
                 $phpdoc = $this->extractDocumentation($method->getDocComment());
-                $optiondoc = array_key_exists($pname, $phpdoc['params']) ? $phpdoc['params'][$pname] : null;
-                if ($optiondoc && $phpdoc['content']) {
+                $optiondoc = array_key_exists($pname, $phpdoc['params']) ? $phpdoc['params'][$pname] : [];
+                if ($phpdoc['content']) {
                     // use method content rather than param if exists
                     $optiondoc['content'] = $phpdoc['content'];
                 }
 
+                $default = 'N/A';
+                if ($rp = $rc->getProperty($pname)) {
+                    $dv = $rp->getDefaultValue();
+                    $default = match (gettype($dv)) {
+                        'boolean' => $dv ? 'true' : 'false',
+                        'array' => '[' . implode(', ', $dv) . ']',
+                    };
+                }
+
                 $options[$pname] = [
                     'type' => $type,
                     'phpdoc' => $optiondoc,
+                    'default' => $default,
                 ];
             }
         }