diff --git a/src/Handlers/OpenApiHandler.php b/src/Handlers/OpenApiHandler.php index 60b5a6d..24cefeb 100644 --- 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 index c36f779..ed2a0f2 100644 --- 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 index 6cd8f02..468520f 100644 --- 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 index 6b1e3f1..f7ab440 100644 --- 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 +
+ Select Example:  +HTML; + foreach ($fullSchema['examples'] as $exampleKey => $exampleValue) { + $example = htmlentities(json_encode($exampleValue, JSON_PRETTY_PRINT)); + $this->description .= <<< HTML +
+ {$exampleKey} +
+HTML; + } + $this->description .= <<< HTML + +
+ +HTML; + } $this->description .= ' '; + . nl2br(str_replace(' ', ' ', json_encode($fullSchema, JSON_PRETTY_PRINT))) . ''; return $form->addTextArea('post_raw', $this->getParamLabel()) ->setHtmlAttribute('rows', 10);