Add required: yes/no to reference docs (#1652)

zircote · Sep 22, 2024 · a6916d1 · a6916d1
1 parent 8e19141
commit a6916d1
Show file tree

Hide file tree

Showing 6 changed files with 801 additions and 779 deletions.
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
@@ -28,3 +28,9 @@
         border-bottom: solid 1px #ddd;
     }
 }
+
+.table-plain, table.table-plain tr, table.table-plain th, table.table-plain td  {
+    border: none;
+    padding: 2px 12px 2px 0;
+    background: none;
+}
diff --git a/docs/reference/annotations.md b/docs/reference/annotations.md
diff --git a/docs/reference/attributes.md b/docs/reference/attributes.md
diff --git a/docs/reference/processors.md b/docs/reference/processors.md
@@ -115,9 +115,6 @@ Generate the OperationId based on the context of the OpenApi annotation.
 </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)
 
 
@@ -151,3 +148,6 @@ Tracks the use of all <code>Components</code> and removed unused schemas.
 </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.
diff --git a/src/Annotations/PathParameter.php b/src/Annotations/PathParameter.php
@@ -25,4 +25,9 @@ class PathParameter extends Parameter
      * @inheritdoc
      */
     public $required = true;
+
+    /**
+     * @inheritdoc
+     */
+    public static $_required = ['name'];
 }
diff --git a/tools/src/Docs/RefGenerator.php b/tools/src/Docs/RefGenerator.php
@@ -163,18 +163,28 @@ public function formatAnnotationsDetails(string $name, string $fqdn, string $fil
 
     protected function getPropertyDocumentation(string $fqdn, string $name): array
     {
+        /** @var class-string<AbstractAnnotation> $class */
+        $class = str_replace('Attributes', 'Annotations', $fqdn);
         try {
-            $rp = new \ReflectionProperty(str_replace('Attributes', 'Annotations', $fqdn), $name);
+            $rp = new \ReflectionProperty($class, $name);
         } catch (\ReflectionException $re) {
             $rp = null;
         }
 
-        return $this->extractDocumentation($rp ? $rp->getDocComment() : null);
+        $documentation = $this->extractDocumentation($rp ? $rp->getDocComment() : null);
+
+        $documentation['required'] = in_array($name, $class::$_required);
+
+        return $documentation;
     }
 
     protected function propertyDetails(array $propertyDocumentation): void
     {
         echo '<p>' . nl2br($propertyDocumentation['content'] ?: self::NO_DETAILS_AVAILABLE) . '</p>';
+
+        echo '<table class="table-plain">';
+        echo '<tr><td><i>Required</i>:</td><td style="padding-left: 0;"><b>' . ($propertyDocumentation['required'] ? 'yes' : 'no') . '</b></td></tr>';
+
         if ($propertyDocumentation['see']) {
             $links = [];
             foreach ($propertyDocumentation['see'] as $see) {
@@ -183,10 +193,11 @@ protected function propertyDetails(array $propertyDocumentation): void
                 }
             }
             if ($links) {
-                echo '<p><i>See</i>: ' . implode(', ', $links) . '</p>';
+                echo '<tr><td style="padding-left: 0;"><i>See</i>:</td><td style="padding-left: 0;">' . implode(', ', $links) . '</td></tr>';
             }
         }
 
+        echo '</table>';
     }
 
     /**