Generate correct Error OpenApi

[Fylax]

In OpenApi both example and examples keyword exist. The difference relies in the fact that example takes one (or more) anonymous example whereas examples requires named examples.

Given the current code, using an anonymous example looked more concise than a named one.

More info available on official doc: https://swagger.io/docs/specification/v3_0/adding-examples/

[soyuka]

Actually a JSON Schema (also in the OpenAPI specification) is described here: https://json-schema.org/draft/2020-12/json-schema-validation#name-examples. It's also written in the OpenAPI Spec (for parameters schemas) that examples will override example. We should only use examples it's more aligned with the JSON Schema specification.

[Fylax]

Considering that OpenApi with examples being an array of scalars complains being invalid (especially, it breaks AWS API Gateway), while the JSON Schema spec accepts any kind of array for the examples, would using examples as an array of object be a reasonable solution in your opinion?

I am thinking of something like

examples:
  NotFoundError:
    value: 404
    summary: HTTP Not Found Error

In that case, how to ensure that example name is unique?

[soyuka]

yes probably but I don't know for sure this needs to be tested against https://github.com/daveshanley/vacuum/ to be sure? You can try it on the openapi doctor: https://pb33f.io/doctor/

[Fylax]

both vacuum and openapi doctor say that examples is not a valid property.

In details:

oai.yaml:4616:11 | error | schema invalid: status is not allowed any additional properties (I found examples).

As an additional information: I noticed that examples is an invalid property in OpenApi 3.0 (only example is allowed), while both example and examples are accepted.

Sadly, AWS API Gateway requires Swagger 2.0 or OpenApi 3.0 (it explicitly rejects the 3.1).

With that said, I can only see 2 options:

1. move to example
2. change between example or examples depending whether the target version is less or equal than 3.1

Personally, I would go with the second option as it sounds more "future-proof", but I honestly have no clue on how to condition it

[soyuka]

There's a legacy bridge for openapi 3.0 at https://github.com/api-platform/core/blob/main/src/OpenApi/Serializer/LegacyOpenApiNormalizer.php maybe its missing this?

[Fylax]

My bad, I wasn't aware of the specific normalizer. I will open a new PR changing the right file