Refactor JsonOutput and OpenApiHandler classes to support multiple ex…

…amples (#143) Co-authored-by: Martin Beranek <[email protected]>
tomaj · Apr 19, 2024 · 5347a71 · 5347a71
1 parent 1c08b32
commit 5347a71
Show file tree

Hide file tree

Showing 4 changed files with 142 additions and 9 deletions.
diff --git a/src/Handlers/OpenApiHandler.php b/src/Handlers/OpenApiHandler.php
@@ -313,6 +313,17 @@ private function getPaths(array $versionApis, string $baseUrl, string $basePath)
                                 ],
                             ]
                         ];
+                        if (!empty($examples = $output->getExamples())) {
+                            if (count($examples) === 1) {
+                                $example = is_array($output->getExample())? $output->getExample() : json_decode($output->getExample(), true);
+                                $responses[$output->getCode()]['content']['application/json; charset=utf-8']['example'] = $example;
+                            } else {
+                                foreach ($examples as $exampleKey => $example) {
+                                    $example = is_array($example)? $example : json_decode($example, true);
+                                    $responses[$output->getCode()]['content']['application/json; charset=utf-8']['examples'][$exampleKey] = $example;
+                                }
+                            }
+                        }
                     } else {
                         if (!isset($responses[$output->getCode()]['content']['application/json; charset=utf-8']['schema']['oneOf'])) {
                             $tmp = $responses[$output->getCode()]['content']['application/json; charset=utf-8']['schema'];
@@ -476,8 +487,14 @@ private function createRequestBody(ApiHandlerInterface $handler)
         foreach ($handler->params() as $param) {
             if ($param instanceof JsonInputParam) {
                 $schema = json_decode($param->getSchema(), true);
-                if ($param->getExample()) {
-                    $schema['example'] = $param->getExample();
+                if (!empty($examples = $param->getExamples())) {
+                    if (count($examples) === 1) {
+                        $schema['example'] = is_array($param->getExample())? $param->getExample() : json_decode($param->getExample(), true);
+                    } else {
+                        foreach ($examples as $exampleKey => $example) {
+                            $schema['examples'][$exampleKey] = is_array($example)? $example : json_decode($example, true);
+                        }
+                    }
                 }
                 return [
                     'description' => $param->getDescription(),
@@ -493,8 +510,12 @@ private function createRequestBody(ApiHandlerInterface $handler)
                 $schema = [
                     'type' => 'string',
                 ];
-                if ($param->getExample()) {
-                    $schema['example'] = $param->getExample();
+                if (!empty($examples = $param->getExamples())) {
+                    if (count($examples) === 1) {
+                        $schema['example'] = $param->getExample();
+                    } else {
+                        $schema['examples'] = $examples;
+                    }
                 }
                 return [
                     'description' => $param->getDescription(),

diff --git a/src/Output/AbstractOutput.php b/src/Output/AbstractOutput.php
@@ -10,6 +10,9 @@ abstract class AbstractOutput implements OutputInterface
 
     protected $description;
 
+    /** @var array */
+    protected $examples = [];
+
     public function __construct(int $code, string $description = '')
     {
         $this->code = $code;
@@ -25,4 +28,48 @@ public function getDescription(): string
     {
         return $this->description;
     }
+
+    /**
+     * @param string $name Example name
+     * @param mixed $example Example
+     * @return Self
+     */
+    public function addExample(string $name, $example): self
+    {
+        $this->examples[$name] = $example;
+        return $this;
+    }
+
+    /**
+     * Set default example
+     * @param mixed $example
+     * @return self
+     * @deprecated Use addExample instead
+     */
+    public function setExample($example): self
+    {
+        $this->examples["default"] = $example;
+        return $this;
+    }
+
+    /**
+     * Returns first example
+     * @return mixed
+     */
+    public function getExample()
+    {
+        if (empty($this->examples)) {
+            return null;
+        }
+        return reset($this->examples);
+    }
+
+    /**
+     * Returns all examples
+     * @return array
+     */
+    public function getExamples(): array
+    {
+        return $this->examples;
+    }
 }
diff --git a/src/Params/InputParam.php b/src/Params/InputParam.php
@@ -44,8 +44,8 @@ abstract class InputParam implements ParamInterface
     /** @var mixed */
     protected $default;
 
-    /** @var mixed */
-    protected $example;
+    /** @var array */
+    protected $examples = [];
 
     public function __construct(string $key)
     {
@@ -128,21 +128,48 @@ public function getDefault()
     }
 
     /**
+     * Add example, can be used multiple times to add many examples
+     * @param string $name Example name
+     * @param mixed $example Example
+     * @return Self
+     */
+    public function addExample(string $name, $example): self
+    {
+        $this->examples[$name] = $example;
+        return $this;
+    }
+
+    /**
+     * Set default example
      * @param mixed $example
      * @return self
+     * @deprecated Use addExample instead
      */
     public function setExample($example): self
     {
-        $this->example = $example;
+        $this->examples["default"] = $example;
         return $this;
     }
 
     /**
+     * Returns first example
      * @return mixed
      */
     public function getExample()
     {
-        return $this->example;
+        if (empty($this->examples)) {
+            return null;
+        }
+        return reset($this->examples);
+    }
+
+    /**
+     * Returns all examples
+     * @return array
+     */
+    public function getExamples(): array
+    {
+        return $this->examples;
     }
 
     public function updateConsoleForm(Form $form): void

diff --git a/src/Params/JsonInputParam.php b/src/Params/JsonInputParam.php
@@ -66,10 +66,48 @@ public function getSchema(): string
 
     protected function addFormInput(Form $form, string $key): BaseControl
     {
+        $fullSchema = json_decode($this->schema, true);
+
+        if (!empty($examples = $this->getExamples())) {
+            if (count($examples) === 1) {
+                $fullSchema['example'] = is_array($this->getExample())? $this->getExample() : json_decode($this->getExample(), true);
+            } else {
+                foreach ($examples as $exampleKey => $example) {
+                    $fullSchema['examples'][$exampleKey] = is_array($example)? $example : json_decode($example, true);
+                    // pretty formatting of json example if decoded
+                }
+            }
+        }
+
+
+        if (!empty($fullSchema['examples'])) {
+            $this->description .= <<< HTML
+                <div>
+                    Select Example:&nbsp; 
+HTML;
+            foreach ($fullSchema['examples'] as $exampleKey => $exampleValue) {
+                $example = htmlentities(json_encode($exampleValue, JSON_PRETTY_PRINT));
+                $this->description .= <<< HTML
+                <div class="btn btn-sm" data-example="{$example}" onClick="setExample(this)" >
+                    {$exampleKey}
+                </div>
+HTML;
+            }
+            $this->description .= <<< HTML
+                <script>
+                    function setExample(btn) {
+                        var input = document.getElementsByName('post_raw')[0];
+                        input.value = btn.dataset.example;
+                    }
+                </script>
+                </div>
+
+HTML;
+        }
         $this->description .= '<div id="show_schema_link"><a href="#" onclick="document.getElementById(\'json_schema\').style.display = \'block\'; document.getElementById(\'show_schema_link\').style.display = \'none\'; return false;">Show schema</a></div>
                             <div id="json_schema" style="display: none;">
                             <div><a href="#" onclick="document.getElementById(\'show_schema_link\').style.display = \'block\'; document.getElementById(\'json_schema\').style.display = \'none\'; return false;">Hide schema</a></div>'
-            . nl2br(str_replace(' ', '&nbsp;', json_encode(json_decode($this->schema), JSON_PRETTY_PRINT))) . '</div>';
+            . nl2br(str_replace(' ', '&nbsp;', json_encode($fullSchema, JSON_PRETTY_PRINT))) . '</div>';
 
         return $form->addTextArea('post_raw', $this->getParamLabel())
             ->setHtmlAttribute('rows', 10);