Support for OpenAPI 3.1

[glenncoppens]

Hi,

I tried to generate an api client based on a json openapi v3.1.0 (https://docs.publiq.be/docs/uitdatabank/taxonomy-api%2Fopenapi-file), but validation fails as OAS3.1 seems to be not (yet) supported.

I've listed some of the validation exceptions:

• "Unsupported openapi version: 3.1.0"
• "Reference: additional properties are given. Only $ref should be set in a Reference Object."
• "Invalid key 'Event-@id' used in Components Object for attribute 'schemas', does not match ^[a-zA-Z0-9\\.\\-_]+$."
• "Invalid key 'Organizer-@id' used in Components Object for attribute 'schemas', does not match ^[a-zA-Z0-9\\.\\-_]+$."

What could/should be done to provide support for OAS 3.1?
I'm not familiar with the inner workings and detailed OAS specs, but open to collaborate.

PS: tried to downgrade the json from 3.1 to 3.0 which, when trying to generate the api client afterwards, only throwed the "Invalid key" exceptions twice.

Thanks,

Glenn

[vsouz4]

Hi @glenncoppens, can you please share the command you used so I can try to reproduce it?

OAS3.1 should be supported out of the box so it could be something with the spec, I pasted it in https://editor.swagger.io/ and it shows some similar warnings...

Additionally, maybe you have a YAML version to test?

[glenncoppens]

@vsouz4
Yes indeed, you're right! Unfortunately I don't have a yml file available though.

Command i used:

OPENAPI=data/uitdatabank-entry-api.json NAMESPACE=UitDatabank\Api PACKAGE=uitdatabank/api OUTPUT_DIR=dist/src php ./bin/api-client-generator generate

I've tried using de 'official' php-generator from the openapi-generator cli (didn't know that one before yours, it's java based) and it resulted in the same errors. Although they have an option to ignore validation errors, which made it work in the end but then again, not sure if it has a negative impact on the resulting php source code.

On the other hand they don't fully support php8 (yet) for the generated client as per my understanding.

So I'm quite stuck on how to proceed 😅

[vsouz4]

thx for the command, I ran it here and did some debugging, ik what the issue is 😄 please bear with me:

• this generator uses cebe/php-openapi to parse the file and the lib doesn't support OAS 3.1 so yes, you're right, this generator currently doesn't support OAS 3.1
  • this cebe/php-openapi has an open issue for this topic Support OpenAPI 3.1 cebe/php-openapi#101, but not much interest in pushing this forward apparently
• for your case specifically, you can edit the json to be able to generate a php 8 client with our generator if you do this:
  • use "openapi": "3.0.0" instead of "openapi": "3.1.0" (guess you tried that already but there's 1 more thing you need to do)
  • change the get-terms operationId to getTerms, apparently we have an issue with dashes in operationId
  • you can keep the 2 "examples" keys (which are not compatible with 3.0.0) because they will simply be ignored by the generator

I'll open an issue here in github for this operationId handling to be fixed, and we can keep your issue opened to add proper support for OAS 3.1, but I hope with these 2 changes you can generate your client in the meantime

[glenncoppens]

@vsouz4

Oh thanks!

But I see I pasted the wrong OpenAPI file, it should have been this one: https://stoplight.io/api/v1/projects/publiq/uitdatabank/nodes/reference/entry.json?deref=optimizedBundle

But as per your suggestion I've managed to remove those errors you mentioned.

There's only one error left:

"Reference: additional properties are given
  . Only $ref should be set in a Reference Object.","Invalid key 'Event-@id' used in Co
  mponents Object for attribute 'schemas', does not match ^[a-zA-Z0-9\\.\\-_]+$.","Inva
  lid key 'Organizer-@id' used in Components Object for attribute 'schemas', does not m
  atch ^[a-zA-Z0-9\\.\\-_]+$.","Invalid key 'Place-@id' used in Components Object for a
  ttribute 'schemas', does not match ^[a-zA-Z0-9\\.\\-_]+$.", 

... omitted

But I'm guessing it's related by having a dash in the key?

I've attached a version of the OpenApi file with already renamed "operationId" keys.
entry-api-3.json

Is it possible to rename those key references with a "-@" to achieve an OAS3.0 compatible version?

[vsouz4]

I'm able to generate a client if:

• you replace openapi: 3.1.0 with openapi: 3.0.0
• you rename all operationId to camelCase (btw created a PR to fix that, will merge as soon as it gets approved fix operation id with dashes #107)
• you remove the 1 endpoint (operationId: image-post) that requires multipart/form-data from the spec because that's also not currently supported
• you remove the peer properties to $ref (allowed in json schema / oas 3.1 but not in oas 3.0) - they're irrelevant for the client generation anyways
  • how I did that with vim:
  • :%s/\([^"]*\)".*,\n\s*"\($ref.*\)/\1"\2/
  • :%s/\($ref": .*\),\n\s*"description.*/\1/
• you replace the -@ with just -
  • :%s/-@/-

but FYI the generated code will completely ignore the "if" / "then" and "dependentRequired" from json schema / oas 3.1 (and any other props I might've missed)

last but not least, we currently don't support type: oauth2 in security still, so this is also being ignored atm, any help is very much appreciated to add support for that

[tomhatzer]

Hey @vsouz4 🤗
Thank you very much for building the api client generator.

OpenAPI 3.1 support has been built into the fork of the cebe parser here: https://github.com/DEVizzent/cebe-php-openapi
The thephpleague also switched to that fork.

Would it be possible to change the api-client-generator also to this fork?

Thank you very much and have a lovely day!

[vsouz4]

hi @tomhatzer

Thx for sharing this fork, I've created a PR with your suggestion