swagger-php Files

Corrects the schema examples handling introduced in 6.8.0.

Upgrading from 6.7.x

6.8.0 changed generated output and the release notes did not say so. @OA\Examples nested under an @OA\Schema or @OA\Property used to emit a keyed map, which no validator accepts. It now emits the list of values JSON Schema calls for:

:::diff
 YoYo:
   examples:

-    yo:
-      summary: 'the yo'
-      value: YoYo
+    - YoYo

summary, description and externalValue have nowhere to go in a list and are dropped, and an example carrying no value contributes nothing. For Example Objects use a media type, parameter or header — their examples is a map and keeps every field.

Fixed

• @OA\Examples under a schema no longer reports a missing example key-field or a missing summary; neither reaches the output (#2177)
• summary is no longer required on @OA\Examples anywhere — the Example Object has no required fields in the specification
• A schema's examples now accepts plain values, in attributes and docblocks alike, and keeps the order you write when mixed with @OA\Examples: php #[OA\Property(type: 'integer', examples: [80, 443])]
• The Items attribute's constructor docblock is repaired, so the reference page shows its declared parameter types instead of falling back to the native ones

New diagnostics

Cases that used to pass in silence now warn: an @OA\Examples under a schema with no value, value and externalValue set together, and any other annotation passed as an example.

The cookbook has a new section on schema examples and how they differ from a media type's.

What's Changed

• fix(Attributes): repair the Items constructor docblock by @DerManoMann in https://github.com/zircote/swagger-php/pull/2179

Stacked on [#2178] and squash-merged, so it carries that change too — most of this release is in that commit.

Full Changelog: https://github.com/zircote/swagger-php/compare/6.8.0...6.8.1