Common errors encountered when updating an OpenAPI document in z/OS Connect Designer

How to fix common errors that are encountered when an OpenAPI document is updated in z/OS Connect Designer.

Some of the API project paths, operations, and mappings might break as a result of updating the OpenAPI document. The following are common errors that might occur when updating an OpenAPI document, and how to fix them.

OpenAPI document path deletion
If you deleted a path from the OpenAPI document,
  1. Go to the src/main/operations folder within your API project.
  2. Delete the folder corresponding to that path.

This is not mandatory but it avoids having folders in the API project that are no longer needed.

For example, if you delete the path /employees/{id}, the folder to delete would be %2Femployees%2F%7Bid%7D.

OpenAPI document operation deletion
If you deleted an operation from a particular path in the OpenAPI document,
  1. Go to the src/main/operations folder within your API project.
  2. Go to the folder for the path whose operation is removed.
  3. Delete the folder corresponding to the operation.

This is not mandatory but it avoids having folders in the API project that are no longer needed.

For example, if the PUT operation is deleted in the /employees/{id} path,
  1. Go to src/main/operations (path) folder.
  2. Go to %2Femployees%2F%7Bid%7D (path) folder.
  3. Delete the put (operation) folder.
OpenAPI document response code deletion
If you deleted a response code from a particular operation of any path in the OpenAPI document,
  1. Go to the src/main/operations folder within your API project.
  2. Go to the folder for the respective path of the response code.
  3. Go to the folder for the respective operation.
  4. Delete the response_xxx.yaml file that corresponds to the response code deleted from the operation.
For example, if you deleted the response code 404 in the PUT operation under the /employees/{id} path,
  1. Go to the src/main/operations folder.
  2. Go to the path folder, %2Femployees%2F%7Bid%7D
  3. Go to the operation folder, put.
  4. Delete the file response_404.yaml.

Also in the z/OS Connect Designer, go to the corresponding operation’s page, click Responses, and ensure that the response conditions for the operation are valid. If needed, update the conditions.

If you have not made any changes here, ensure that there are no references to the deleted response code in the API project. To do this,
  1. Go to the src/main/operations folder within your API project.
  2. Go to the folder for the respective path.
  3. Go to the folder for the respective operation.
  4. Open the response_mapping.yaml file. Check whether there are any conditions set for the deleted response code. If yes, delete the block for that response code from this file and save.
OpenAPI document - request body or request parameter deletion
If you deleted a field from the request body or request parameters for a particular operation, of any path in the OpenAPI document, use these steps.
  1. Go to the corresponding operations page in z/OS Connect Designer by using the left navigation.
  2. Click the button that is named after the z/OS Asset used by the operation.
  3. In the mapping editor, ensure that none of the fields that are deleted from either the request body or request parameters are used. If used, update the input field to use something from the available mappings. Close the panel.
  4. Click Responses. In the condition editor, ensure that none of the deleted fields are used. Close the panel.
  5. In the mapping editor, click each response code button and ensure that none of the deleted fields are used.
OpenAPI document - response body or response parameter deletion
If you deleted a field from the response body or response headers for a response code, of a particular operation, of any path in the OpenAPI document.
  1. Go to the src/main/operations folder within your API project.
  2. Go to the folder for the respective path.
  3. Go to the folder for the respective operation. For example, put.
  4. Open the response_xxx.yaml file that corresponds to the response code under which you deleted a field. In the yaml file, delete the mappings that use the deleted field.