Refactor JsonOutput and OpenApiHandler classes to support multiple examples

src/Handlers/OpenApiHandler.php

@@ -313,6 +313,19 @@ private function getPaths(array $versionApis, string $baseUrl, string $basePath)
                                 ],
                             ]
                         ];
+                        if (!empty($output->getAdditionalExamples())) {  //Multiple examples processing
+                            $examples = array_merge(
+                                ["default" => is_array($output->getExample())? $output->getExample() : json_decode($output->getExample(), true)],
+                                $output->getAdditionalExamples(),
+                            );
+                            $examples = $this->transformSchema($examples);
+                            $responses[$output->getCode()]['content']['application/json; charset=utf-8']['examples'] = $examples;
+                        }
+                        else if (!empty($output->getExample())) { //One example processing
+                            $example = $output->getExample();
+                            $example = $this->transformSchema(is_array($example)? $example : json_decode($example, true));
+                            $responses[$output->getCode()]['content']['application/json; charset=utf-8']['example'] = $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 +489,18 @@ 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($param->getAdditionalExamples())) {  //Multiple examples processing
+                    $examples = array_merge(
+                        ["default" => is_array($param->getExample())? $param->getExample() : json_decode($param->getExample(), true)],
+                        $param->getAdditionalExamples(),
+                    );
+                    $examples = $this->transformSchema($examples);
+                    $schema['examples'] = $examples;
+                }
+                else if (!empty($param->getExample())) { //One example processing
+                    $example = $param->getExample();
+                    $example = $this->transformSchema(is_array($example)? $example : json_decode($example, true));
+                    $schema['example'] = $example;
                 }
                 return [
                     'description' => $param->getDescription(),

src/Output/JsonOutput.php

@@ -14,6 +14,15 @@ class JsonOutput extends AbstractOutput
 {
     private $schema;
 
+    /** @var mixed */
+    private $example;
+
+    /** @var array 
+     * 
+     * 
+    */
+    private $additionalExamples = [];
+
     public function __construct(int $code, string $schema, string $description = '')
     {
         parent::__construct($code, $description);
@@ -39,4 +48,54 @@ public function getSchema(): string
     {
         return $this->schema;
     }
+
+    /**
+     * @param mixed $example
+     */
+    public function setExample($example): self
+    {
+        $this->example = $example;
+        return $this;
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getExample()
+    {
+        return $this->example;
+    }
+
+    /**
+     * Set multiple examples for request. This is useful for testing. 
+     * Associative names will be used as example name. 
+     * [
+     *  "A" => [ "param1" => "value1", "param2" => "value2" ],
+     *  "B" => [ "param1" => "value3", "param2" => "value4" ]
+     * ]
+     * @param array $examples
+     * @return self
+     */
+    public function setAdditionalExamples(array $examples): self
+    {
+        if (empty($this->example)) {
+            throw new \Exception('You have to set example before you can set additional examples');
+        }
+        foreach ($examples as &$example) {
+            if (!is_array($example)) {
+                $example = json_decode($example, true);
+            }
+        }
+        $this->additionalExamples = $examples;
+        return $this;
+    }
+
+    /**
+     * Get additional examples
+     * @return array
+     */
+    public function getAdditionalExamples(): array  
+    {
+        return $this->additionalExamples;
+    }
 }

src/Params/JsonInputParam.php

@@ -19,6 +19,9 @@ class JsonInputParam extends InputParam
 
     private $rawInput;
 
+    /** @var array */
+    protected $additionalExamples = [];
+
     public function __construct(string $key, string $schema)
     {
         parent::__construct($key);
@@ -64,12 +67,81 @@ public function getSchema(): string
         return $this->schema;
     }
 
+    /**
+     * Set multiple examples for request. This is useful for testing. 
+     * Associative names will be used as example name. 
+     * [
+     *  "A" => [ "param1" => "value1", "param2" => "value2" ],
+     *  "B" => [ "param1" => "value3", "param2" => "value4" ]
+     * ]
+     * @param array $examples
+     * @return self
+     */
+    public function setAdditionalExamples(array $examples): self
+    {
+        if (empty($this->example)) {
+            throw new \Exception('You have to set example before you can set additional examples');
+        }
+        foreach ($examples as &$example) {
+            if (!is_array($example)) {
+                $example = json_decode($example, true);
+            }
+        }
+        $this->additionalExamples = $examples;
+        return $this;
+    }
+
+    /**
+     * Get additional examples
+     * @return array
+     */
+    public function getAdditionalExamples(): array  
+    {
+        return $this->additionalExamples;
+    }
+
     protected function addFormInput(Form $form, string $key): BaseControl
     {
+        $fullSchema = json_decode($this->schema, true);
+
+        if (!empty($this->getAdditionalExamples())) {
+            $fullSchema['examples'] = array_merge(
+                ["default" => is_array($this->getExample())? $this->getExample() : json_decode($this->getExample(), true)],
+                $this->getAdditionalExamples(),
+            );
+        } else {
+            $fullSchema['example'] = is_array($this->getExample())? $this->getExample() : json_decode($this->getExample(), true);
+        }
+
+
+        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);