brammittendorff | 2016-11-23 10:34:46 UTC | #1
To generate a php sdk, I have used the swagger.json from: https://github.com/MyPureCloud/purecloud_api_sdk_javascript
When generated with the swagger-codegen project it will create a nice php sdk to work with. The only problem is in the swagger.json there are enum values called:
"state":{"type":"string","enum":["ALERTING","DIALING","CONTACTING","OFFERING","CONNECTED","DISCONNECTED","TERMINATED","UPLOADING","CONVERTING","TRANSMITTING","NONE"]}
But when the application reaches the purecloud api it will return with a lowercase:
"state":"disconnected"
So when the generated php sdk tries to use those values it will say:
Invalid value for 'state', must be one of 'ALERTING', 'DIALING', 'CONTACTING', 'OFFERING', 'CONNECTED', 'DISCONNECTED', 'TERMINATED', 'CONVERTING', 'UPLOADING', 'TRANSMITTING', 'NONE'
Here below is the automatic generated php code that checks it:
$allowedvalues = array('ALERTING', 'DIALING', 'CONTACTING', 'OFFERING', 'CONNECTED', 'DISCONNECTED', 'TERMINATED', 'CONVERTING', 'UPLOADING', 'TRANSMITTING', 'NONE'); if (!inarray($state, $allowed_values)) { throw new \InvalidArgumentException("Invalid value for 'state', must be one of 'ALERTING', 'DIALING', 'CONTACTING', 'OFFERING', 'CONNECTED', 'DISCONNECTED', 'TERMINATED', 'CONVERTING', 'UPLOADING', 'TRANSMITTING', 'NONE'"); }
-
This topic is created to discuss more about the enum values in the swagger.json file on github:
- MyPureCloud/purecloudapisdk_javascript/issues/16
Potherca | 2016-11-23 10:28:56 UTC | #2
This issue seems to have also occurred in the Python SDK.
brammittendorff | 2016-11-23 11:51:54 UTC | #3
So the question is: What is the reason that the values of the enums are uppercase in the swagger.json while the api returns lowercase values?
tim.smith | 2016-11-30 16:10:48 UTC | #4
There is currently an issue with the way those values are documented in the swagger file. That should be fixed pretty soon if it's not already. However, it's a best practice that any application or SDK robustly handle parsing of these values in case you encounter an unknown value. This can happen when the API releases a new version with new values and your SDK hasn't been updated yet.
Potherca | 2016-11-30 19:16:03 UTC | #5
it's a best practice that any application or SDK robustly handle parsing of these values in case you encounter an unknown value.
This is not applicable to the issue raised here. The issue is with know values that are incorrectly defined in the swagger file in the linked repo.
In regards to
There is currently an issue with the way those values are documented in the swagger file. That should be fixed pretty soon if it's not already.
Where can the fix be found (or progress followed)?
Related to this issue (as mentioned in the Github Issue we are using the swagger.json to generate a PHP SDK. We were wondering where the generated swagger file comes from as there seem to be different files in different SDK's. In other words: is there is a canonical source?
One would think that, once the issues in the swagger file have been resolved, it should be trivial to generate SDK's in all of the languages that the Swagger CodeGen supports without too much meddling.
tim.smith | 2016-11-30 19:22:28 UTC | #6
The issue is with know values that are incorrectly defined in the swagger file in the linked repo.
Part of robustly handling them is to do case-insensitive comparisons. You can choose to do a case-insensitive comparison and have the enums work, or you can do a case sensitive comparison and get a parsing error. Choose whichever works best for handling the situation in your application. All of the SDKs have been updated to use a case-insensitive comparison specifically to prevent this issue with enums, as well as handling completely unknown values.
Where can the fix be found (or progress followed)?
I have verified that the fix is in production already. If there are any resources that still have a difference between documented values and what the API is sending, please make a new forum topic to report the resource and we'll address it.
We were wondering were the generated swagger file comes from
This is always the current swagger definition at the time it is retrieved and is what the SDKs pull from when they are generated: https://api.mypurecloud.com/api/v2/docs/swagger
One would think that, once the issues in the swagger file have been resolved, it should be trivial to generate SDK's in all of the languages that the Swagger CodeGen supports without too much meddling.
All of the languages have required some meddling thus far. :) Releasing additional SDKs incurs additional effort for development, testing, maintenance, and support, so we only support languages that have a known userbase. So far, this discussion has been the only request for a PHP SDK.
brammittendorff | 2016-12-13 10:42:25 UTC | #7
The problem in this case was we did not know which swagger file we needed. So we tried every swagger file there were in the github repository without success. But we found the solution with your help so here are the steps to take for a good PHP SDK/API are:
1 Download the swagger-codegen-cli:
2 Download the correct swagger file:
3 Create a config.json (for PSR copmliance we use camelCase):
{
"modelPackage": "PureCloudSDK",
"apiPackage" : "PureCloudSDK\\Api",
"invokerPackage": "PureCloudSDK",
"packagePath": "PureCloudSDK",
"srcBasePath": "PureCloudSDK",
"composerProjectName": "PureCloudSDK",
"variableNamingConvention": "camelCase"
}
4 Generate a php sdk with the codegen-cli:
java -jar swagger-codegen-cli.jar generate -i api-swagger.json -c config.json -l php -o .
tim.smith | 2016-12-09 16:28:44 UTC | #8
Did you have to make any changes to any templates or the swagger-codegen project? Or does the SDK work with the vanilla generator?
brammittendorff | 2016-12-13 10:34:08 UTC | #9
Nope I did not make any changes. It works as described above.
tim.smith | 2016-12-13 15:08:51 UTC | #10
Thanks! We're prioritizing additional SDKs in Q1 and will include PHP for consideration.
system | 2017-08-28 19:29:00 UTC | #11
This post was migrated from the old Developer Forum.
ref: 660