Starting the z/OS Connect Designer with Docker and importing an OpenAPI definition

Use the docker compose command to start the z/OS Connect Designer.

About this task

This topic is applicable to:

Learn how to start the z/OS Connect Designer and access it in your web browser.

When z/OS Connect Designer is running, you import the OpenAPI definition to start configuring your API. For this tutorial, the OpenAPI definition is the file EmployeesApi.yaml.

1. Instantiate your container.
   Change to the ZCWorkspace directory and run the following command.

   docker compose up -d

   This command starts a container and loads the z/OS Connect Designer image. The -d option instructs Docker to run the command in the background.

   Attention: You might see a delay of 10 - 15 seconds while the z/OS Connect Designer starts before you see progress messages. Switch to Docker to see the messages under the Containers/Apps.

   You can check whether the z/OS Connect Designer is started by running the following command.

   docker ps

   The following output indicates that the container is running.

   CONTAINER ID    IMAGE              COMMAND         CREATED       STATUS       PORTS                      NAMES
   f73c93115331    icr.io/zosconnect/ibm-zcon-designer:3.0.75          “/opt/ibm/helpers/ru…”  4 seconds ago    Up 2 seconds    0.0.0.0:9080->9080/tcp, 0.0.0.0:9443->9443/tcp  zcworkspace_zosConnect_1

2. Open the z/OS Connect Designer UI in your browser.
   Enter the following URL in a web browser to view the z/OS Connect Designer.

   https://localhost:9443/zosConnect/designer

   Tip: If you use port 9443, use the Firefox web browser to view the z/OS Connect Designer. Other web browsers might not allow communication between the z/OS Connect Designer container and your web browser. This is because the z/OS Connect Designer uses a self-signed certificate.

   If you use port 9080 (HTTP), enter the following URL:

   http://localhost:9080/zosConnect/designer

   The import screen for the z/OS Connect Designer is displayed.

   

   The z/OS Connect Designer container is running in the Docker runtime on your local workstation. By running docker compose up, the z/OS Connect Designer image is instantiated with the EmployeesApi, logs, and certs directories mounted to this running container.

3. Import the OpenAPI definition, EmployeesApi.yaml for the Employee management API for Db2 into your API project.

   The file is provided in the Db2 sample in the GitHub repository at start/src/main/api/openapi.yaml.

   You can drag the EmployeesApi.yaml file into z/OS Connect Designer or select it from the file system viewer.

   Note: You can review and edit the EmployeesApi.yaml file by using your choice of the OpenAPI definition viewer. A common tool is the Swagger editor https://editor.swagger.io/

   After you import the OpenAPI definition into z/OS Connect Designer, a preview of the name, description, and version is presented.

   

4. Click Create API to create the project.
   When processing is complete, the Information page is presented.

   

5. Explore the z/OS Connect Designer interface.
   You can see the paths and operations that are defined in the EmployeesApi.yaml. Warning indicators in the left navigation window show where your input is needed. Paths are endpoints (resources) that your API exposes, such as /employees/{id} or /employees and operations are the HTTP methods that are used to manipulate these paths, such as GET, PUT, POST, or DELETE. The next sections provide more information about resolving these warnings.