fix(Annotations): add the Info Object's summary field

docs/reference/annotations.md

@@ -399,6 +399,10 @@ The metadata may be used by the clients if needed and may be presented in editin
 <dl>
   <dt><strong>title</strong> : <span style="font-family: monospace;">string</span></dt>
   <dd><p>The title of the application.</p><table class="table-plain"><tbody><tr><td><i>Required</i>:</td><td style="padding-left: 0;"><b>yes</b></td></tr></tbody></table></dd>
+  <dt><strong>summary</strong> : <span style="font-family: monospace;">string</span></dt>
+  <dd><p>A short summary of the API.<br />
+<br />
+Exists as of 3.1; a 3.0 document omits it.</p><table class="table-plain"><tbody><tr><td><i>Required</i>:</td><td style="padding-left: 0;"><b>no</b></td></tr></tbody></table></dd>
   <dt><strong>description</strong> : <span style="font-family: monospace;">string</span></dt>
   <dd><p>A short description of the application.<br />
 <br />

docs/reference/attributes.md

@@ -1003,6 +1003,10 @@ These will be ignored but can be used for custom processing.</p><table class="ta
 CommonMark syntax may be used for rich text representation.</p><table class="table-plain"><tbody><tr><td><i>Required</i>:</td><td style="padding-left: 0;"><b>no</b></td></tr></tbody></table></dd>
   <dt><strong>title</strong> : <span style="font-family: monospace;">string|null</span></dt>
   <dd><p>The title of the application.</p><table class="table-plain"><tbody><tr><td><i>Required</i>:</td><td style="padding-left: 0;"><b>yes</b></td></tr></tbody></table></dd>
+  <dt><strong>summary</strong> : <span style="font-family: monospace;">string|null</span></dt>
+  <dd><p>A short summary of the API.<br />
+<br />
+Exists as of 3.1; a 3.0 document omits it.</p><table class="table-plain"><tbody><tr><td><i>Required</i>:</td><td style="padding-left: 0;"><b>no</b></td></tr></tbody></table></dd>
   <dt><strong>termsOfService</strong> : <span style="font-family: monospace;">string|null</span></dt>
   <dd><p>An URL to the Terms of Service for the API.<br />
 <br />

src/Annotations/Info.php

@@ -26,6 +26,15 @@ class Info extends AbstractAnnotation
      */
     public $title = Undefined::UNDEFINED;
 
+    /**
+     * A short summary of the API.
+     *
+     * Exists as of 3.1; a 3.0 document omits it.
+     *
+     * @var string
+     */
+    public $summary = Undefined::UNDEFINED;
+
     /**
      * A short description of the application.
      *
@@ -75,6 +84,7 @@ class Info extends AbstractAnnotation
      */
     public static $_types = [
         'title' => 'string',
+        'summary' => 'string',
         'version' => 'string',
         'description' => 'string',
         'termsOfService' => 'string',
@@ -95,4 +105,15 @@ class Info extends AbstractAnnotation
     public static $_parents = [
         OpenApi::class,
     ];
+
+    public function jsonSerialize(): \stdClass
+    {
+        $data = parent::jsonSerialize();
+
+        if ($this->_context->isVersion('3.0.x')) {
+            unset($data->summary);
+        }
+
+        return $data;
+    }
 }

src/Attributes/Info.php

@@ -20,6 +20,7 @@ public function __construct(
         ?string $version = null,
         ?string $description = Undefined::UNDEFINED,
         ?string $title = null,
+        ?string $summary = null,
         ?string $termsOfService = null,
         ?Contact $contact = null,
         ?License $license = null,
@@ -32,6 +33,7 @@ public function __construct(
                 'version' => $version ?? Undefined::UNDEFINED,
                 'description' => $description,
                 'title' => $title ?? Undefined::UNDEFINED,
+                'summary' => $summary ?? Undefined::UNDEFINED,
                 'termsOfService' => $termsOfService ?? Undefined::UNDEFINED,
                 'x' => $x ?? Undefined::UNDEFINED,
                 'attachables' => $attachables ?? Undefined::UNDEFINED,

src/HybridBridge.php

@@ -234,6 +234,7 @@ protected function convertInfo(OA\Info $info): Spec\Info
             version: $this->val($info->version),
             contact: $contact,
             license: $license,
+            summary: $this->val($info->summary),
             x: $this->extensions($info),
         );
     }

tests/Fixtures/Scratch/InfoObject-spec.php

@@ -0,0 +1,29 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Tests\Fixtures\Scratch;
+
+use OpenApi\Spec as OA;
+
+// summary exists as of 3.1; the 3.0 document omits it.
+// Stacked siblings: Contact and License merge into the Info.
+#[OA\Info(
+    version: '1.0',
+    title: 'InfoObject',
+    summary: 'A short summary of the API',
+    description: 'What the API is for, at more length.',
+    termsOfService: 'https://example.com/terms',
+)]
+#[OA\Contact(name: 'Support', url: 'https://example.com/support', email: 'support@example.com')]
+#[OA\License(name: 'MIT')]
+class InfoObjectControllerSpec
+{
+    #[OA\Operation\Get(path: '/endpoint', operationId: 'endpoint')]
+    #[OA\Response(response: 200, description: 'OK')]
+    public function endpoint(): void
+    {
+    }
+}

tests/Fixtures/Scratch/InfoObject.php

@@ -0,0 +1,33 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Tests\Fixtures\Scratch;
+
+use OpenApi\Attributes as OAT;
+
+// summary exists as of 3.1; the 3.0 document omits it
+#[OAT\Info(
+    version: '1.0',
+    title: 'InfoObject',
+    summary: 'A short summary of the API',
+    description: 'What the API is for, at more length.',
+    termsOfService: 'https://example.com/terms',
+    contact: new OAT\Contact(name: 'Support', url: 'https://example.com/support', email: 'support@example.com'),
+    license: new OAT\License(name: 'MIT'),
+)]
+class InfoObjectController
+{
+    #[OAT\Get(
+        path: '/endpoint',
+        operationId: 'endpoint',
+        responses: [
+            new OAT\Response(response: 200, description: 'OK'),
+        ],
+    )]
+    public function endpoint(): void
+    {
+    }
+}

tests/Fixtures/Scratch/InfoObject3.0.0.yaml

@@ -0,0 +1,19 @@
+openapi: 3.0.0
+info:
+  title: InfoObject
+  description: 'What the API is for, at more length.'
+  termsOfService: 'https://example.com/terms'
+  contact:
+    name: Support
+    url: 'https://example.com/support'
+    email: support@example.com
+  license:
+    name: MIT
+  version: '1.0'
+paths:
+  /endpoint:
+    get:
+      operationId: endpoint
+      responses:
+        200:
+          description: OK

tests/Fixtures/Scratch/InfoObject3.1.0.yaml

@@ -0,0 +1,20 @@
+openapi: 3.1.0
+info:
+  title: InfoObject
+  description: 'What the API is for, at more length.'
+  termsOfService: 'https://example.com/terms'
+  contact:
+    name: Support
+    url: 'https://example.com/support'
+    email: support@example.com
+  license:
+    name: MIT
+  summary: 'A short summary of the API'
+  version: '1.0'
+paths:
+  /endpoint:
+    get:
+      operationId: endpoint
+      responses:
+        200:
+          description: OK

tests/Fixtures/Scratch/InfoObject3.2.0.yaml

@@ -0,0 +1,20 @@
+openapi: 3.2.0
+info:
+  title: InfoObject
+  description: 'What the API is for, at more length.'
+  termsOfService: 'https://example.com/terms'
+  contact:
+    name: Support
+    url: 'https://example.com/support'
+    email: support@example.com
+  license:
+    name: MIT
+  summary: 'A short summary of the API'
+  version: '1.0'
+paths:
+  /endpoint:
+    get:
+      operationId: endpoint
+      responses:
+        200:
+          description: OK