diff --git a/docs/reference/annotations.md b/docs/reference/annotations.md index d343b954c..901011f1d 100644 --- a/docs/reference/annotations.md +++ b/docs/reference/annotations.md @@ -399,6 +399,10 @@ The metadata may be used by the clients if needed and may be presented in editin
title : string

The title of the application.

Required:yes
+
summary : string
+

A short summary of the API.
+
+Exists as of 3.1; a 3.0 document omits it.

Required:no
description : string

A short description of the application.

diff --git a/docs/reference/attributes.md b/docs/reference/attributes.md index 6fccdf558..136e0d218 100644 --- a/docs/reference/attributes.md +++ b/docs/reference/attributes.md @@ -1003,6 +1003,10 @@ These will be ignored but can be used for custom processing.

Required:no
title : string|null

The title of the application.

Required:yes
+
summary : string|null
+

A short summary of the API.
+
+Exists as of 3.1; a 3.0 document omits it.

Required:no
termsOfService : string|null

An URL to the Terms of Service for the API.

diff --git a/src/Annotations/Info.php b/src/Annotations/Info.php index 995ad5e0f..7094d13f6 100644 --- a/src/Annotations/Info.php +++ b/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; + } } diff --git a/src/Attributes/Info.php b/src/Attributes/Info.php index eede5b2a5..93b5ae6fa 100644 --- a/src/Attributes/Info.php +++ b/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, diff --git a/src/HybridBridge.php b/src/HybridBridge.php index 3e00bea4e..0bd98593c 100644 --- a/src/HybridBridge.php +++ b/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), ); } diff --git a/tests/Fixtures/Scratch/InfoObject-spec.php b/tests/Fixtures/Scratch/InfoObject-spec.php new file mode 100644 index 000000000..da9efaa11 --- /dev/null +++ b/tests/Fixtures/Scratch/InfoObject-spec.php @@ -0,0 +1,29 @@ +