From 23822178b22367a60c24988bc832fcd86e74b6b4 Mon Sep 17 00:00:00 2001 From: Martin Rademacher Date: Tue, 2 Jul 2024 15:56:29 +1200 Subject: [PATCH] Improve processor reference (#1617) --- docs/reference/processors.md | 44 ++++++++++++++++++++---- src/Processors/AugmentParameters.php | 5 ++- src/Processors/CleanUnusedComponents.php | 6 ++-- src/Processors/OperationId.php | 2 +- src/Processors/PathFilter.php | 2 -- tools/procgen.php | 6 +++- tools/refgen.php | 1 + tools/src/Docs/DocGenerator.php | 2 -- tools/src/Docs/ProcGenerator.php | 14 ++++++-- 9 files changed, 64 insertions(+), 18 deletions(-) diff --git a/docs/reference/processors.md b/docs/reference/processors.md index 4629e830..7375b25b 100644 --- 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
augmentParameters.augmentOperationParameters : bool
-

No details available.

+
default : : true
+

If set to true try to find operation parameter descriptions in the operation docblock.

@@ -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
operationId.hash : bool
-

No details available.

+
default : : true
+

If set to true generate ids (md5) instead of clear text operation ids.

+### [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 tags 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 +
+
pathFilter.tags : array
+
default : : []
+

A list of regular expressions to match tags to include.

+
+
+
pathFilter.paths : array
+
default : : []
+

A list of regular expressions to match paths to include.

+
+ + ### [CleanUnusedComponents](https://github.com/zircote/swagger-php/tree/master/src/Processors/CleanUnusedComponents.php) +Tracks the use of all Components and removed unused schemas. +#### Config settings +
+
cleanUnusedComponents.enabled : bool
+
default : : false
+

Enables/disables the CleanUnusedComponents processor.

+
+ diff --git a/src/Processors/AugmentParameters.php b/src/Processors/AugmentParameters.php index 47670724..2c882ba6 100644 --- 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 index 624ae7e4..1871c81f 100644 --- 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 CleanUnusedComponents processor. + */ public function setEnabled(bool $enabled): CleanUnusedComponents { $this->enabled = $enabled; diff --git a/src/Processors/OperationId.php b/src/Processors/OperationId.php index 0e799b07..b6aff2ca 100644 --- 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 index 13c3fd5e..b393d468 100644 --- 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 index bfbcd203..f6018dda 100644 --- 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 = ' : ' . $odetails['type'] . ''; + $default = ' : ' . $odetails['default'] . ''; + echo '
' . PHP_EOL; echo '
' . $configPrefix . $name . '' . $var . '
' . PHP_EOL; + echo '
default : ' . $default . '
' . PHP_EOL; echo '
'; echo '

' . nl2br($odetails['phpdoc'] ? $odetails['phpdoc']['content'] : ProcGenerator::NO_DETAILS_AVAILABLE) . '

'; echo '
' . PHP_EOL; diff --git a/tools/refgen.php b/tools/refgen.php index 3f0d62eb..e88ea5c1 100644 --- 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 index 6fbb15b9..40eec2d6 100644 --- 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 index b35e3849..5a2857a6 100644 --- 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, ]; } }