BC Support for OpenApi v3.0.x

[mab05k]

Description
As of API Platform 3.2+, OpenApi output with spec_version=3 defaults to OpenApi 3.1.x

Some third party systems do not support import with OpenAPI 3.1 spec. (Currently Azure APIM does not accept OpenAPI generated from API Platform).

Asking for the api:openapi:export command to support spec_version=3.0 and spec_version=3.1

[soyuka]

It's been a while that this is out, Microsoft is an OpenAPI Member maybe we can ask them to update? For now you can fix this with a custom normalizer and remove what's not supported. If you do so I'll be glad to accept a contribution.

[mab05k]

Thanks for the quick response @soyuka. I have reached out to Microsoft support to ask about updating and limitations and am also working on custom normalization for my project. If I come up with something useful / reusable I'll post here.

For awareness anyone anyone else facing the same issue, they are throwing errors for nullable types and they don't like the owl:maxCadinality annotation.

"properties": {
      "id": {
          "type": [ // Generates an error in APIM
              "integer",
              "null"
          ]
      },
      "type": {
          "owl:maxCardinality": 1, // Generates an error in APIM
          "type": "number",
          "example": 1,
          "nullable": false
      },
     ....

[bytecast-de]

Hi @soyuka @mab05k ,

aside from Microsoft there are still a lot of tools out there struggling to support the v3.1 specification.

We're using openapi-generator (https://github.com/OpenAPITools/openapi-generator/) for automatic generation of PHP client-code - currently not supporting v3.1 (OpenAPITools/openapi-generator#9083).
Also the underlying swagger parser has many open issues regarding v3.1 (https://github.com/swagger-api/swagger-parser/issues?q=is%3Aissue+is%3Aopen+3.1.0+author%3Aspacether)

So, if there's any chance api plaform can be configured to explicitly change between v3.0 and v3.1, this would be of great help.

[soyuka]

automatic generation of PHP client-code

I think that https://github.com/api-platform/schema-generator supports it no?

Also the underlying swagger parser has many open issues regarding v3.1 (https://github.com/swagger-api/swagger-parser/issues?q=is%3Aissue+is%3Aopen+3.1.0+author%3Aspacether)

Damn... I wish they had not refactored the whole parser and instead just update the old one...

For the type issues above you can override #[ApiProperty(schema: ['type' => 'integer']), it's also doable programmatically using a PropertyMetadataFactoryInterface that decorate ours.

I don't have many ideas, or we create a normalizer that tries to remove non-compatible stuff (a pain to maintain). I'm open to suggestions, is there anything else then types regarding Microsoft?

[soyuka]

can you try my patch?

[mab05k]

@soyuka The logic looks good, but it doesn't seem to be persisting the changes to the output. The output for these types are still coming out the same for me. Perhaps getting overridden somewhere else later in the process?

I came to a similar solution in my OpenApiFactory decorator. However, I used the anyOf syntax for multiple types.

foreach ($schemas as $name => $component) {
    foreach ($component['properties'] ?? [] as $property => $value) {
        if (is_array($value['type'] ?? false)) {
            foreach ($value['type'] as $type) {
                $schemas[$name]['properties'][$property]['anyOf'][] = ['type' => $type];
            }
            unset($schemas[$name]['properties'][$property]['type']);
        }
        unset($value['owl:maxCardinality']);
    }
}

Some other things I noticed. The change is giving an error when running from CLI and sending a request to the Docs page without the ?spec_version=3.0 query param. Or also if I request the docs page from https://localhost. It looks like these requests end up going through the EntrypointAction instead of the DocumentationAction.

With the CLI, passing in --spec_version=3.0 did not fix the issue.

{
  "@context": "\/contexts\/Error",
  "@type": "hydra:Error",
  "hydra:title": "An error occurred",
  "hydra:description": "Warning: Undefined array key \u0022spec_version\u0022",
  "trace": [
    {
      "namespace": "",
      "short_class": "",
      "class": "",
      "type": "",
      "function": "",
      "file": "\/srv\/app\/vendor\/api-platform\/core\/src\/OpenApi\/Serializer\/LegacyOpenApiNormalizer.php",
      "line": 34,
      "args": []
    },
    {
      "namespace": "ApiPlatform\\OpenApi\\Serializer",
      "short_class": "LegacyOpenApiNormalizer",
      "class": "ApiPlatform\\OpenApi\\Serializer\\LegacyOpenApiNormalizer",
      "type": "-\u003E",
      "function": "normalize",
      "file": "\/srv\/app\/vendor\/symfony\/serializer\/Debug\/TraceableNormalizer.php",
      "line": 58,
      "args": [
        [
          "object",
          "ApiPlatform\\OpenApi\\OpenApi"
        ],
        [
          "string",
          "json"
        ],
        [
          "array",
          {
            "debug_trace_id": [
              "string",
              "657724d9464ec"
            ]
          }
        ]
      ]
    },
    ...
  ]
}

[soyuka]

indeed I added this only to the DocumentationAction. You could've proposed a patch your code is pretty similar to what I have, may I add this to my PR? I'll add some test anyways thanks for the feedback!

[mab05k]

Yes @soyuka please feel free to use those changes. Thank you. You guys and API Platform are awesome :)

[soyuka]

will be released by the end of the week