Legacy Dev Forum Posts

 View Only

Sign Up

Back to discussions
Expand all | Collapse all

Swagger definition does not match API

  • 1.  Swagger definition does not match API

    Posted 06-05-2025 18:29

    Hans-Gerd_Sandhagen | 2024-02-04 18:13:08 UTC | #1

    Hello,

    for some reasons I created my own C#-SDK from swagger (https://api.mypurecloud.com/api/v2/docs/swagger).

    It works fine, but I found, til now, 2 mismatches between the swagger (and the documentation in API explorer) and the behaviour of the API.

    1. Wrong response definition in PUT /api/v2/conversations/calls/{conversationId}/recordingstate

    Schema in API Explorer: (unstructured primitive) (string) Valid values: ACTIVE, PAUSED, NONE.

    In Swagger:

    Path: "/api/v2/conversations/calls/{conversationId}/recordingstate" Operation "put" Responses: "200"

    "200": { "description": "successful operation", "schema": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "NONE" ] } },

    which matches the schema description in API Explorer.

    This means the response body should look like this: "ACTIVE"

    But if I call the API I get a response like this: { "recordingState": "ACTIVE" }

    1. Missing response in /api/v2/conversations/{conversationId}/recordings/{recordingId}

    API Responses in API Exlorer don't list response "200" but response "202 - recording is transcoding" only. Nevertheless the schema is shown of response "200"

    this matches the swagger definition:

    Path: /api/v2/conversations/{conversationId}/recordings/{recordingId} Operation: GET Responses:

    "responses": { "202": { "description": "Success - recording is transcoding", "schema": { "$ref": "#/definitions/Recording" } }, ....

    The API responses "202" without body when it is called the first time and "200" with the data f the recording in the body when it is called the second time.

    I think it is a bug in the swagger.

    Is the swagger definition generated from the API code or is made "by hand" in some way?

    Zino_Onokpise | 2024-02-05 18:26:29 UTC | #2

    Hi Hans-Gerd_Sandhagen,

    Could you explain #1 further? not sure what you mean there

    Hans-Gerd_Sandhagen | 2024-02-06 17:23:15 UTC | #3

    Hi Zino_Onokpise,

    in API-Explorer for the Path /api/v2/conversations/calls/{conversationId}/recordingstate the Schema for response 200 and 202 is

    (unstructured primitive) (string) Valid values: ACTIVE, PAUSED, NONE

    That means, the body of the response is "ACTIVE" , "PAUSED" or "NONE". Returning a string only might be not very common, but matches the definition in swagger:

    "/api/v2/conversations/calls/{conversationId}/recordingstate": { "put": { .... "responses": { "200": { "description": "successful operation", "schema": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "NONE" ] } }, "202": { "description": "Accepted - when pausing or resuming recordings (Secure Pause)", "schema": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "NONE" ] } },

    But when I call the API, I get the following response: { "recordingState": "PAUSED" }

    This needs different parsing to get the Value ACTIVE , PAUSED or NONE.

    tim.smith | 2024-02-06 17:29:46 UTC | #4

    @Hans-Gerd_Sandhagen this is a bug in the API's definition and must be reported via Care. In case you get any pushback on that report, this can only be handled via Care because fixing the schemas in the documentation is accomplished via a code change to the Public API itself. This means that it is a core product bug and therefore must be handled by Care so it is tracked as a customer-reported issue and handled according to the associated contractual SLAs.

    system | 2024-03-07 17:30:13 UTC | #5

    This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.

    This post was migrated from the old Developer Forum.

    ref: 24471



Related Content