Trouble generating a PHP client via swagger

Any issue about Cyclos 4 scripting and Webservices

Moderators: rmvanarkel, hugo, alexandre

Post Reply
jakob.schumann
Posts: 20
Joined: Thu Apr 23, 2020 5:37 pm

Trouble generating a PHP client via swagger

Post by jakob.schumann »

Hello,

when using swagger-codegen (v3.0.19) to create a PHP client the classes are generated (result in https://github.com/bueffelsoft/cyclos-rest-api) from the .../api/cyclos-openapi.json

But the generated client is not functional: Requests can be made, authentication works but the responses cannot be deserialized but cause fatal errors in the ObjectSerializer.php.
Does anyone else have those issues? Is there another way to get a working PHP client for the REST-API?

The problems are manyfold and probably stem from inconsistencies in the API documentation and Swagger not working correctly in edge cases:

1) Many properties have no type specified or the type cannot be detected, which causes the generator to set the type to an empty string, e.g. https://github.com/bueffelSOFT/cyclos-r ... er.php#L60
This causes "Uncaught Error: Class '' not found in cyclos-rest-api/lib/ObjectSerializer.php on line 305" which can be manually fixed by patching https://github.com/bueffelSOFT/cyclos-r ... r.php#L249 to:

Code: Select all

} elseif ($class === 'object' || $class === '') {
so empty types are returned as array.

2) For many properties the generator can detect a type and also generates a class for it but fails to add the PHP namespace to it: https://github.com/bueffelSOFT/cyclos-r ... og.php#L59 while other types (see L61 in the same file) correctly have the namespace added to the model. This causes for example "Error: Class 'AllOfBaseAuthPermissions' not found in cyclos-rest-api/lib/ObjectSerializer.php on line 305" which can be fixed by either adding the namespace manually to all thos cases or adding

Code: Select all

            if (!class_exists($class) && class_exists('\Cyclos\Api\Model\\'.$class)) {
                    $class = '\Cyclos\Api\Model\\'.$class;
            }
after https://github.com/bueffelSOFT/cyclos-r ... r.php#L291

This is probably caused by the API documentation using "allOf" in many cases where the direct type would be better: http://prntscr.com/s5441q

3) For some properties the generator detects inheritance, e.g. https://github.com/bueffelSOFT/cyclos-r ... le.php#L41. And for thoses classes tries to reuse the types declaration (L75 in this file), formats declaration (L85) and class constructor (L165). But those methods don't exist in the parent class which again causes a fatal PHP error.
Probably caused like 2) by using "allOf" instead of the type?

From my knowledge, the REST API is preferred over the RPC interface, what is the correct way to get a working PHP client?

Best regards,
J.Schumann
andres
Posts: 5
Joined: Fri Dec 16, 2011 9:31 am
Location: Montevideo, Uruguay

Re: Trouble generating a PHP client via swagger

Post by andres »

If you use the OpenAPI generator (https://openapi-generator.tech/#try) instead of swagger-codegen the error
you indicate in 1) doesn't happen (it seems it's a bug in Swagger)

Regardless the generator you use, both have bugs, e.g the openapi-gen also has the same problem of not prepending the namespace to some models (we need to use allOf to have a description accociated to a reference, please check this: https://github.com/OAI/OpenAPI-Specific ... ssues/2033)

At this moment the PHP generation throught openapi/swagger codegen is not working due bugs they have, we suggest use a php lib to generate the HTTP request you need (e.g. http://docs.guzzlephp.org/en/stable/)
Andrés Meyer
Cyclos development team
jakob.schumann
Posts: 20
Joined: Thu Apr 23, 2020 5:37 pm

Re: Trouble generating a PHP client via swagger

Post by jakob.schumann »

Hello Andres,

thanks for your input!

It's a little bit disappointing that the swagger codegen is so buggy for OAv3, I used it successfully with Swagger / OpenApi v2 before.

The OpenApi generator you mentioned indeed creates PHP classes without error 1) but only if I skip the spec validation, else it notifies about some errors in the cyclos-openapi.json. (Using with docker run --rm -v $PWD:/local openapitools/openapi-generator-cli generate -i /local/cyclos-openapi.json -g php -o /local/out/php)

Code: Select all

Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
 | Error count: 3, Warning count: 9
Errors:
        -attribute paths.'/validate/email-change/{key}'(post).operationId is repeated
        -attribute paths.'/validate/registration/{key}'(post).operationId is repeated
        -attribute paths.For path parameter kind the required value should be true
Warnings:
        -attribute paths.'/validate/email-change/{key}'(post).operationId is repeated
        -attribute paths.'/validate/registration/{key}'(post).operationId is repeated
        -attribute paths.For path parameter kind the required value should be true
So it seems we have to wait for OA3.1 to drop and the generators to support it...
We already started on a custom client, based on a stripped version of the code generated by the swagger codegen.

Thanks again,
Jakob
Post Reply