Examples property of different object

[sintro]

According to https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-20, 'example' property was renamed to 'examples' (I think the same right for schema``s properties, but this is not clear enough from spec).
Anyway, with 3.1.0 version of Generator it renders 'example' property:

openapi: 3.1.0
info:
  title: 'Test'
  version: '1'
components:
  schemas:
    import_props:
      title: 'Import props'
      required:
        - data
        - entity_id
        - mode
      properties:
        data:
          description: 'Data'
          type: string
          format: binary
      example:
        -
          example: 'Example 1'
          summary: 'Example 1'
          value:
            mode: create
            entity_id: 1
            data: data
        -
          example: 'Example 1'
          summary: 'Example 1'
          value:
            mode: update
            entity_id: 1
            data: data

This is produced with code inside OA\Schema

#[OA\Schema(
        ...
        example: [
            new OA\Examples(
                example: 'Example 1',
                summary: 'Example 1',
                value: [
                    'mode' => 'create',
                    'entity_id' => 1,
                    'data' => 'data'
                ]
            ),
            new OA\Examples(
                example: 'Example 1',
                summary: 'Example 1',
                value: [
                    'mode' => 'update',
                    'entity_id' => 1,
                    'data' => 'data'
                ]
            ),
        ],
        ...

The same happens with OA\Property`s 'example' prop.

[DerManoMann]

Created a scratch test illustrating the use, see #1561.

The spec says example is deprecated, not renamed. You can use either ATM, however for multiple examples examples is the preferred way.

Should be:

#[OA\Schema(
        ...
        examples: [
            new OA\Examples(
                example: 'Example 1',

[sintro]

Thank for answer, but as I can see from you code you showed the usage of 'examples' attribute of QueryParameter class, which was not problem in this particalar issue. The problem is that there are no same attributes in Schema class and its Property class, only single example attributes:

swagger-php/src/Attributes/Schema.php

Line 59 in d3265da

mixed $example = Generator::UNDEFINED,

swagger-php/src/Attributes/Property.php

Line 60 in d3265da

mixed $example = Generator::UNDEFINED,

How is it possible to produce "examples" for Schema and schema`s properties with "example" attribute?

[DerManoMann]

Ha! Got me there. I suppose Schema should then also get an examples property I suppose. However, the spec does not show one, so either that is an oversight in the spec or intentional.

Using spectral it seems examples is only available in a schema in 3.1.0.

Did some more surgery on the PR - should work now.

[sintro]

Still, validator from https://editor-next.swagger.io/ tells "property "example" is deprecated, use "examples" instead" for Schema`s properties also.
Also, "examples" property of schema now rendered not as array in yaml:

      examples:
        'Example 1':
          summary: 'Example 1'
          value:
            mode: create
            entity_id: 1
            data: data
        'Example 2':
          summary: 'Example 1'
          value:
            mode: update
            entity_id: 1
            data: data

Produced by:

examples: [
        new OA\Examples(
            example: 'Example 1',
            summary: 'Example 1',
            value: [
                'mode' => 'create',
                'entity_id' => 1,
                'data' => 'data'
            ]
        ),
        new OA\Examples(
            example: 'Example 2',
            summary: 'Example 1',
            value: [
                'mode' => 'update',
                'entity_id' => 1,
                'data' => 'data'
            ]
        ),
    ]

[DerManoMann]

None of the snippets here show examples as array so I think it is just fair to treat them the same everywhere.

spectral is happy with the current implementation, so I guess it will be hard to keep everyone happy, unless someone has the definite source of truth.