refactor: better spec extensions support

Author: itsjavi

src/ExtensionProperty.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace erasys\OpenApi;
+
+/**
+ * Specification Extension property definition.
+ */
+class ExtensionProperty
+{
+    /**
+     * Exact name of the property that will be used in the generated schema.
+     *
+     * @var string
+     */
+    public $name;
+
+    /**
+     * Value of the property
+     *
+     * @var mixed
+     */
+    public $value;
+
+    /**
+     * @param string     $name
+     * @param mixed|null $value
+     */
+    public function __construct(string $name, $value = null)
+    {
+        $this->name  = $name;
+        $this->value = $value;
+    }
+}

src/Spec/v3/AbstractObject.php

@@ -3,6 +3,7 @@
 namespace erasys\OpenApi\Spec\v3;
 
 use ArrayAccess;
+use erasys\OpenApi\ExtensionProperty;
 use erasys\OpenApi\RawValue;
 use Illuminate\Contracts\Support\Arrayable;
 use Illuminate\Contracts\Support\Jsonable;
@@ -117,23 +118,47 @@ public function toArray()
     private function exportValue($value)
     {
         if ($value instanceof RawValue) {
+            // Unwrap value and return it raw, as it is.
             return $value->value;
         }
 
         if ($value instanceof AbstractObject) {
             return $value->toArray();
         }
 
+        if ($value instanceof ExtensionProperty) {
+            return [
+                $value->name => $this->exportValue($value->value),
+            ];
+        }
+
         if (is_array($value)) {
             $result = [];
             foreach ($value as $k => $v) {
                 // Ignore null properties
                 if (is_null($v)) {
                     continue;
                 }
-                // Transform extension property names
-                if (preg_match('/^x[A-Z]/', $k)) {
-                    $k = 'x-' . lcfirst(preg_replace('/^(x)/', '', $k));
+                // Take key and value from extension property definition
+                if ($v instanceof ExtensionProperty) {
+                    $result[$v->name] = $this->exportValue($v->value);
+                    continue;
+                }
+                if (in_array($k, ['xml'])) {
+                    $result[$k] = $this->exportValue($v);
+                    continue;
+                }
+                // Transform extension property names using the 'x-dashes-format'
+                if (preg_match('/^x[_]/', $k)) {
+                    $k          = str_replace('_', '-', $k);
+                    $result[$k] = $this->exportValue($v);
+                    continue;
+                }
+                // Transform extension property names using the 'x-camelCaseFormat'
+                if (preg_match('/^x[A-Za-z]/', $k)) {
+                    $k          = 'x-' . lcfirst(preg_replace('/^(x)/', '', $k));
+                    $result[$k] = $this->exportValue($v);
+                    continue;
                 }
                 // Transform reference property names
                 if ($k === 'ref') {

src/Spec/v3/AbstractParameter.php

@@ -5,9 +5,8 @@
 /**
  * Common class for Parameter Object and Header Object.
  */
-abstract class AbstractParameter extends AbstractObject
+abstract class AbstractParameter extends AbstractObject implements ExtensibleInterface
 {
-
     /**
      * A brief description of the parameter. This could contain examples of use.
      * CommonMark syntax MAY be used for rich text representation.

src/Spec/v3/Components.php

@@ -8,9 +8,8 @@
  *
  * @see https://swagger.io/specification/#componentsObject
  */
-class Components extends AbstractObject
+class Components extends AbstractObject implements ExtensibleInterface
 {
-
     /**
      * A map to hold reusable Schema Objects.
      *

src/Spec/v3/Contact.php

@@ -7,9 +7,8 @@
  *
  * @see https://swagger.io/specification/#contactObject
  */
-class Contact extends AbstractObject
+class Contact extends AbstractObject implements ExtensibleInterface
 {
-
     /**
      * The identifying name of the contact person/organization.
      *

src/Spec/v3/Document.php

@@ -7,14 +7,14 @@
  *
  * @see https://swagger.io/specification/
  */
-class Document extends AbstractObject
+class Document extends AbstractObject implements ExtensibleInterface
 {
-
     const SCHEME_HTTP                 = 'http';
     const SCHEME_HTTPS                = 'https';
     const SCHEME_WEBSOCKET            = 'ws';
     const SCHEME_SECURE_WEBSOCKET     = 'wss';
     const MIME_TYPE_JSON              = 'application/json';
+    const MIME_TYPE_JSON_SCHEMA       = 'application/schema+json';
     const MIME_TYPE_URLENCODED        = 'application/x-www-form-urlencoded';
     const MIME_TYPE_MULTIPART         = 'multipart/form-data';
     const PARAM_IN_PATH               = 'path';

src/Spec/v3/Encoding.php

@@ -7,9 +7,8 @@
  *
  * @see https://swagger.io/specification/#encodingObject
  */
-class Encoding extends AbstractObject
+class Encoding extends AbstractObject implements ExtensibleInterface
 {
-
     /**
      * The Content-Type for encoding a specific property.
      * Default value depends on the property type: for string with format being

src/Spec/v3/Example.php

@@ -7,9 +7,8 @@
  *
  * @see https://swagger.io/specification/#exampleObject
  */
-class Example extends AbstractObject
+class Example extends AbstractObject implements ExtensibleInterface
 {
-
     /**
      * Short description for the example.
      *

src/Spec/v3/ExtensibleInterface.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace erasys\OpenApi\Spec\v3;
+
+/**
+ * Marker interface to identify al OpenAPI elements that MAY have
+ * specification extension properties "x-".
+ *
+ * Currently this includes all elements excepting Discriminator and Reference objects.
+ */
+interface ExtensibleInterface
+{
+
+}

src/Spec/v3/Info.php

@@ -8,9 +8,8 @@
  *
  * @see https://swagger.io/specification/#infoObject
  */
-class Info extends AbstractObject
+class Info extends AbstractObject implements ExtensibleInterface
 {
-
     /**
      * REQUIRED. The title of the application.
      *