OpenAPI: add Exaple implementation add type hints to OpenAPI schema o…

…bject properties

Signed-off-by: Roman Ondráček <[email protected]>

src/OpenApi/Schema/Callback.php

@@ -6,7 +6,7 @@ class Callback
 {
 
 	/** @var mixed[] */
-	private $data = [];
+	private array $data = [];
 
 	/**
 	 * @param mixed[] $data

src/OpenApi/Schema/Components.php

@@ -6,31 +6,31 @@ class Components
 {
 
 	/** @var Schema[]|Reference[] */
-	private $schemas = [];
+	private array $schemas = [];
 
 	/** @var Response[]|Reference[] */
-	private $responses = [];
+	private array $responses = [];
 
 	/** @var Parameter[]|Reference[] */
-	private $parameters = [];
+	private array $parameters = [];
 
 	/** @var Example[]|Reference[] */
-	private $examples = [];
+	private array $examples = [];
 
 	/** @var RequestBody[]|Reference[] */
-	private $requestBodies = [];
+	private array $requestBodies = [];
 
 	/** @var Header[]|Reference[] */
-	private $headers = [];
+	private array $headers = [];
 
 	/** @var SecurityScheme[]|Reference[] */
-	private $securitySchemes = [];
+	private array $securitySchemes = [];
 
 	/** @var Link[]|Reference[] */
-	private $links = [];
+	private array $links = [];
 
 	/** @var Callback[]|Reference[] */
-	private $callbacks = [];
+	private array $callbacks = [];
 
 	/**
 	 * @param mixed[] $data
@@ -56,6 +56,12 @@ public static function fromArray(array $data): Components
 			}
 		}
 
+		if (isset($data['examples'])) {
+			foreach ($data['examples'] as $exampleKey => $exampleData) {
+				$components->setExample($exampleKey, Example::fromArray($exampleData));
+			}
+		}
+
 		if (isset($data['requestBodies'])) {
 			foreach ($data['requestBodies'] as $requestBodyKey => $requestBodyData) {
 				$components->setRequestBody($requestBodyKey, RequestBody::fromArray($requestBodyData));
@@ -101,6 +107,14 @@ public function setParameter(string $name, $parameter): void
 		$this->parameters[$name] = $parameter;
 	}
 
+	/**
+	 * @param Example|Reference $example
+	 */
+	public function setExample(string $name, $example): void
+	{
+		$this->examples[$name] = $example;
+	}
+
 	/**
 	 * @param RequestBody|Reference $requestBody
 	 */
@@ -143,6 +157,10 @@ public function toArray(): array
 			$data['parameters'][$parameterKey] = $parameter->toArray();
 		}
 
+		foreach ($this->examples as $exampleKey => $example) {
+			$data['examples'][$exampleKey] = $example->toArray();
+		}
+
 		foreach ($this->requestBodies as $requestBodyKey => $requestBody) {
 			$data['requestBodies'][$requestBodyKey] = $requestBody->toArray();
 		}

src/OpenApi/Schema/Contact.php

@@ -6,13 +6,13 @@ class Contact
 {
 
 	/** @var string|null */
-	private $name;
+	private ?string $name = null;
 
 	/** @var string|null */
-	private $url;
+	private ?string $url = null;
 
 	/** @var string|null */
-	private $email;
+	private ?string $email = null;
 
 	/**
 	 * @return mixed[]

src/OpenApi/Schema/Example.php

@@ -5,12 +5,116 @@
 class Example
 {
 
+	private ?string $summary = null;
+
+	private ?string $description = null;
+
+	/** @var mixed|null */
+	private $value = null;
+
+	private ?string $externalValue = null;
+
+	/**
+	 * @param mixed[] $data
+	 * @return self
+	 */
+	public static function fromArray(array $data): self
+	{
+		$example = new Example();
+		$example->summary = $data['summary'] ?? null;
+		$example->description = $data['description'] ?? null;
+		$example->value = $data['value'] ?? null;
+		$example->externalValue = $data['externalValue'] ?? null;
+		return $example;
+	}
+
 	/**
 	 * @return mixed[]
 	 */
 	public function toArray(): array
 	{
-		return [];
+		$data = [];
+		if ($this->summary !== null) {
+			$data['summary'] = $this->summary;
+		}
+
+		if ($this->description !== null) {
+			$data['description'] = $this->description;
+		}
+
+		if ($this->value !== null) {
+			$data['value'] = $this->value;
+		}
+
+		if ($this->externalValue !== null) {
+			$data['externalValue'] = $this->externalValue;
+		}
+
+		return $data;
+	}
+
+	/**
+	 * @return string|null
+	 */
+	public function getSummary(): ?string
+	{
+		return $this->summary;
+	}
+
+	/**
+	 * @param string|null $summary
+	 */
+	public function setSummary(?string $summary): void
+	{
+		$this->summary = $summary;
+	}
+
+	/**
+	 * @return string|null
+	 */
+	public function getDescription(): ?string
+	{
+		return $this->description;
+	}
+
+	/**
+	 * @param string|null $description
+	 */
+	public function setDescription(?string $description): void
+	{
+		$this->description = $description;
+	}
+
+	/**
+	 * @return mixed|null
+	 */
+	public function getValue()
+	{
+		return $this->value;
+	}
+
+	/**
+	 * @param mixed|null $value
+	 */
+	public function setValue($value): void
+	{
+		$this->value = $value;
+	}
+
+	/**
+	 * @return string|null
+	 */
+	public function getExternalValue(): ?string
+	{
+		return $this->externalValue;
+	}
+
+	/**
+	 * @param string|null $externalValue
+	 */
+	public function setExternalValue(?string $externalValue): void
+	{
+		$this->externalValue = $externalValue;
 	}
 
 }

src/OpenApi/Schema/ExternalDocumentation.php

@@ -6,10 +6,10 @@ class ExternalDocumentation
 {
 
 	/** @var string|null */
-	private $description;
+	private ?string $description = null;
 
 	/** @var string */
-	private $url;
+	private string $url;
 
 	public function __construct(string $url)
 	{

src/OpenApi/Schema/Header.php

@@ -6,10 +6,10 @@ class Header
 {
 
 	/** @var string|null */
-	private $description;
+	private ?string $description = null;
 
 	/** @var Schema|Reference|null */
-	private $schema;
+	private $schema = null;
 
 	/**
 	 * @param mixed[] $data

src/OpenApi/Schema/Info.php

@@ -6,22 +6,22 @@ class Info
 {
 
 	/** @var string */
-	private $title;
+	private string $title;
 
 	/** @var string|null */
-	private $description;
+	private ?string $description = null;
 
 	/** @var string|null */
-	private $termsOfService;
+	private ?string $termsOfService = null;
 
 	/** @var Contact|null */
-	private $contact;
+	private ?Contact $contact = null;
 
 	/** @var License|null */
-	private $license;
+	private ?License $license = null;
 
 	/** @var string */
-	private $version;
+	private string $version;
 
 	public function __construct(string $title, string $version)
 	{

src/OpenApi/Schema/License.php

@@ -6,10 +6,10 @@ class License
 {
 
 	/** @var string */
-	private $name;
+	private string $name;
 
 	/** @var string|null */
-	private $url;
+	private ?string $url = null;
 
 	public function __construct(string $name)
 	{

src/OpenApi/Schema/MediaType.php

@@ -11,6 +11,9 @@ class MediaType
 	/** @var mixed */
 	private $example;
 
+	/** @var string[]|Example[]|Reference[] */
+	private array $examples = [];
+
 	/**
 	 * @param mixed[] $data
 	 */
@@ -26,6 +29,16 @@ public static function fromArray(array $data): MediaType
 		}
 
 		$mediaType->setExample($data['example'] ?? null);
+		if (isset($data['examples'])) {
+			foreach ($data['examples'] as $name => $example) {
+				if (isset($example['$ref'])) {
+					$mediaType->addExample($name, new Reference($example['$ref']));
+				} else {
+					$mediaType->addExample($name, Example::fromArray($example));
+				}
+			}
+		}
+
 		return $mediaType;
 	}
 
@@ -61,6 +74,14 @@ public function setExample($example): void
 		$this->example = $example;
 	}
 
+	/**
+	 * @param Example|Reference|string $example
+	 */
+	public function addExample(string $name, $example): void
+	{
+		$this->examples[$name] = $example;
+	}
+
 	/**
 	 * @return mixed[]
 	 */
@@ -75,6 +96,12 @@ public function toArray(): array
 			$data['example'] = $this->example;
 		}
 
+		if ($this->examples !== []) {
+			$data['examples'] = array_map(static function ($example) {
+				return is_string($example) ? $example : $example->toArray();
+			}, $this->examples);
+		}
+
 		return $data;
 	}
 

src/OpenApi/Schema/OAuthFlow.php

@@ -15,7 +15,7 @@ class OAuthFlow
 	private string $refreshUrl;
 
 	/** @var array<string, string> */
-	private array $scopes;
+	private array $scopes = [];
 
 	/**
 	 * @param string $authorizationUrl

src/OpenApi/Schema/OpenApi.php

@@ -6,28 +6,28 @@ class OpenApi
 {
 
 	/** @var string */
-	private $openapi;
+	private string $openapi;
 
 	/** @var Info */
-	private $info;
+	private Info $info;
 
 	/** @var Server[] */
-	private $servers = [];
+	private array $servers = [];
 
 	/** @var Paths */
-	private $paths;
+	private Paths $paths;
 
 	/** @var Components|null */
-	private $components;
+	private ?Components $components = null;
 
 	/** @var SecurityRequirement[] */
-	private $security = [];
+	private array $security = [];
 
 	/** @var Tag[] */
-	private $tags = [];
+	private array $tags = [];
 
 	/** @var ExternalDocumentation|null */
-	private $externalDocs;
+	private ?ExternalDocumentation $externalDocs = null;
 
 	public function __construct(string $openapi, Info $info, Paths $paths)
 	{