[Feature]: (fully) support `Examples` on Property

[bramslob]

Problem Statement

swagger-php v6 exposes examples on OA\Property and OA\Schema, but schema/property examples still do not work correctly for OpenAPI 3.1.

There appear to be two related issues.

First, OA\Property(..., examples: [new OA\Examples(...)]) is accepted by the attribute constructor API, but the nested examples do not merge or serialize. From code inspection, Attributes\Property accepts examples, but Annotations\Property::$_nested does not allow Examples::class, and Annotations\Examples::$_parents does not allow Property::class.

Second, OA\Schema(..., examples: [new OA\Examples(...)]) appears to model schema examples using Example Object semantics, while schema examples should be emitted as a plain array of literal example values. In other words, parameter/media-type examples and schema examples are being treated the same, but they are different shapes in OpenAPI.

This looks related to issue #1560 , but the current behavior in 6.1.0 still appears incomplete for schema/property examples.

When I have this piece of code

   use OpenApi\Attributes as OA;

    // 

    #[OA\Property(description: 'Name of the Category', example: 'Category name', examples: [new OA\Examples(example: 'default', summary: 'Category name example', value: 'Category name')])]
    private ?string $name = null;

and try to build the OpenAPI schema using https://github.com/nelmio/NelmioApiDocBundle, I get the following warning:

User Warning: Unexpected @OA\Examples(), expected to be inside @OA\Components, @OA\Schema, @OA\Parameter, @OA\PathParameter, @OA\MediaType, @OA\JsonContent, @OA\XmlContent in \App\Entity\Category->name   
  in [directory]/src/Entity/Category.php 

Proposed Solution

Complete the implementation by:

• allowing Examples::class under Annotations\Property::$_nested
• allowing Property::class in Annotations\Examples::$_parents
• handling schema/property examples using schema semantics, not parameter/media-type Example Object semantics

Alternatives Considered

No response

Priority

priority/medium

Area

None

Additional Context

No response

[DerManoMann]

What does

handling schema/property examples using schema semantics, not parameter/media-type Example Object semantics

mean? Could you give an example?

[bramslob]

Hey,

I may be wrong, but it LOOKS like there is a difference between the way examples are structured on for instance Parameters as they are are on Schemas.

The place I’m relying on is 4.8.19.2 “Working with Examples”:

https://spec.openapis.org/oas/v3.1.1.html#working-with-examples

That section distinguishes between:

• Parameter/Media Type examples, which use Example Objects
• Schema Object examples, which it describes as “the current plural examples, which takes an array of examples”

And the schema example in 4.8.24.6.5 shows the emitted shape as a plain array of literal values, not Example Objects:

https://spec.openapis.org/oas/v3.1.1.html#model-with-example

So my reading is:

• Parameter.examples / MediaType.examples => map of Example Objects
• Schema.examples => array of literal examples

I of course have to state that my experience or knowledge of the standard is subpar, so I am 100% open to being corrected on this.
I saw there is a PR for this already, which I am (already) very happy with, thanks!

[DerManoMann]

Cool. If you are good with the changes so far I might split off the different behaviour into a separate issue and merge the PR as is?

[bramslob]

Yeah, I think the current set already helps for sure, thanks 🙂

[DerManoMann]

Cool, created #1994 to track the examples differences...