Complete polymorphism example and add to examples in docs (zircote#1735)

Author: DerManoMann

docs/examples/specs/polymorphism/Readme.md

@@ -0,0 +1,3 @@
+## Polymorphism
+
+Demonstrates the use of `Discriminator`

docs/examples/specs/polymorphism/annotations/Controller.php

@@ -29,6 +29,7 @@ class Controller
     /**
      * @OA\Get(
      *     path="/test",
+     *     operationId="test",
      *     description="Get test",
      *     tags={"api"},
      *     @OA\Response(

docs/examples/specs/polymorphism/attributes/AbstractResponsible.php

@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Examples\Specs\Polymorphism\Attributes;
+
+use OpenApi\Attributes as OAT;
+
+#[OAT\Schema(
+    schema: 'Responsible',
+    oneOf: [
+        new OAT\Schema(ref: Fl::class),
+        new OAT\Schema(ref: Employee::class),
+    ],
+    discriminator: new OAT\Discriminator(
+        propertyName: 'type',
+        mapping: [
+            'fl' => '#/components/schemas/FlResponsible',
+            'employee' => '#/components/schemas/EmployeeResponsible',
+        ]
+    )
+)]
+abstract class AbstractResponsible
+{
+    protected const TYPE = null;
+
+    #[OAT\Property(
+        nullable: false,
+        enum: ['employee', 'assignee', 'fl']
+    )]
+    protected string $type;
+
+    public function __construct()
+    {
+        $this->type = static::TYPE;
+    }
+}

docs/examples/specs/polymorphism/attributes/Controller.php

@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Examples\Specs\Polymorphism\Attributes;
+
+use OpenApi\Attributes as OAT;
+
+#[OAT\Info(
+    title: 'Polymorphism',
+    description: 'Polymorphism example',
+    version: '1',
+    contact: new OAT\Contact(
+        name: 'Swagger API Team'
+    )
+)]
+#[OAT\Tag(
+    name: 'api',
+    description: 'API operations'
+)]
+#[OAT\Server(
+    url: 'https://example.localhost',
+    description: 'API server'
+)]
+class Controller
+{
+    #[OAT\Get(
+        path: '/test',
+        operationId: 'test',
+        description: 'Get test',
+        tags: ['api'],
+        responses: [
+            new OAT\Response(
+                response: 200,
+                description: 'Polymorphism',
+                content: new OAT\JsonContent(
+                    ref: Request::class
+                )
+            ),
+        ]
+    )]
+    public function getProduct($id)
+    {
+    }
+}

docs/examples/specs/polymorphism/attributes/Employee.php

@@ -0,0 +1,25 @@
+<?php
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Examples\Specs\Polymorphism\Attributes;
+
+use OpenApi\Attributes as OAT;
+
+#[OAT\Schema(
+    schema: 'EmployeeResponsible'
+)]
+final class Employee extends AbstractResponsible
+{
+    #[OAT\Property(
+        property: 'type'
+    )]
+    protected const TYPE = 'Virtual';
+
+    #[OAT\Property(
+        nullable: false
+    )]
+    public string $property2;
+}

docs/examples/specs/polymorphism/attributes/Fl.php

@@ -0,0 +1,20 @@
+<?php
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Examples\Specs\Polymorphism\Attributes;
+
+use OpenApi\Attributes as OAT;
+
+#[OAT\Schema(
+    schema: 'FlResponsible'
+)]
+final class Fl extends AbstractResponsible
+{
+    public const TYPE = 'fl';
+
+    #[OAT\Property()]
+    public ?string $property3;
+}

docs/examples/specs/polymorphism/attributes/Request.php

@@ -0,0 +1,18 @@
+<?php
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Examples\Specs\Polymorphism\Attributes;
+
+use OpenApi\Attributes as OAT;
+
+#[OAT\Schema()]
+final class Request
+{
+    protected const TYPE = 'employee';
+
+    #[OAT\Property()]
+    public AbstractResponsible $payload;
+}

docs/examples/specs/polymorphism/polymorphism-3.0.0.yaml

@@ -15,7 +15,7 @@ paths:
       tags:
         - api
       description: 'Get test'
-      operationId: c2ce98e75eedefc189265e365c6e54de
+      operationId: test
       responses:
         '200':
           description: Polymorphism

docs/examples/specs/polymorphism/polymorphism-3.1.0.yaml

@@ -15,7 +15,7 @@ paths:
       tags:
         - api
       description: 'Get test'
-      operationId: c2ce98e75eedefc189265e365c6e54de
+      operationId: test
       responses:
         '200':
           description: Polymorphism

docs/guide/examples.md

@@ -299,3 +299,83 @@ Classic petstore sample app. Uses `OAuth`
   </template>
 </codeblock>
 
+
+## Polymorphism
+
+Demonstrates the use of `Discriminator`
+
+### Controller.php
+
+<codeblock id="polymorphism-Controller">
+  <template v-slot:at>
+
+<<< @/examples/specs/polymorphism/attributes/Controller.php
+
+  </template>
+  <template v-slot:an>
+
+<<< @/examples/specs/polymorphism/annotations/Controller.php
+
+  </template>
+</codeblock>
+
+### Request.php
+
+<codeblock id="polymorphism-Request">
+  <template v-slot:at>
+
+<<< @/examples/specs/polymorphism/attributes/Request.php
+
+  </template>
+  <template v-slot:an>
+
+<<< @/examples/specs/polymorphism/annotations/Request.php
+
+  </template>
+</codeblock>
+
+### Employee.php
+
+<codeblock id="polymorphism-Employee">
+  <template v-slot:at>
+
+<<< @/examples/specs/polymorphism/attributes/Employee.php
+
+  </template>
+  <template v-slot:an>
+
+<<< @/examples/specs/polymorphism/annotations/Employee.php
+
+  </template>
+</codeblock>
+
+### AbstractResponsible.php
+
+<codeblock id="polymorphism-AbstractResponsible">
+  <template v-slot:at>
+
+<<< @/examples/specs/polymorphism/attributes/AbstractResponsible.php
+
+  </template>
+  <template v-slot:an>
+
+<<< @/examples/specs/polymorphism/annotations/AbstractResponsible.php
+
+  </template>
+</codeblock>
+
+### Fl.php
+
+<codeblock id="polymorphism-Fl">
+  <template v-slot:at>
+
+<<< @/examples/specs/polymorphism/attributes/Fl.php
+
+  </template>
+  <template v-slot:an>
+
+<<< @/examples/specs/polymorphism/annotations/Fl.php
+
+  </template>
+</codeblock>
+

tools/examplegen.php

@@ -9,7 +9,7 @@
 ob_start();
 echo $gen->preamble('Example');
 
-foreach (['api', 'petstore'] as $name) {
+foreach (['api', 'petstore', 'polymorphism'] as $name) {
     $exampleFolder = $gen->examplePath("specs/$name");
 
     echo PHP_EOL;