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

Use Docker Compose to start the z/OS Connect Designer.

Before you begin

Make sure that all prerequisite tasks are complete:

Prepare the sample IMS application.
Downloading the IMS API project sample.
Downloading the z/OS Connect Designer image.
Creating the IMS tutorial workspace with Docker Desktop.
Configuring connections to IMS with Docker Desktop and Basic Authentication.
Ensure that Docker is running on your workstation.

Remember: You need a Docker runtime version 19.0.3 or later running on your workstation to run the z/OS Connect Designer tool.

Note: When you start the z/OS Connect Designer for the tutorial, port 9443 is used for an HTTPS connection. If you want to try the exercises with an HTTP connection, use port 9080.

About this task

This topic is applicable to: z/OS Connect Designer
capability Content applicable to
application developers

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

Figure 1. z/OS Connect Designer architecture

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 PhonebookApi.yaml.

Procedure

Load the z/OS Connect Designer image into a running 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.

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
```
Open the z/OS Connect Designer UI in your browser.
Attention: The z/OS Connect Designer UI might not appear immediately. Wait 10-15 seconds, then refresh your web 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 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.
Figure 2. z/OS Connect Designer in a web browser

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 PhonebookApi, logs, and certs directories mounted to this running container.
Import the OpenAPI definition, PhonebookApi.yaml for the Phonebook API into your API project.

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

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

Note: You can review and edit the PhonebookApi.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.
Figure 3. An imported OpenAPI definition in the z/OS Connect Designer
Click Create API to create the project.

When processing is complete, the Information page is presented.
Figure 4. An imported OpenAPI definition in the z/OS Connect Designer
Explore the z/OS Connect Designer interface.
You can see the paths and operations that are defined in the PhonebookApi.yaml. Warning indicators in the left navigation window show where your input is needed. Paths are endpoints (resources) that your API exposes, such as /phonebook/contacts/{lastName} 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.

Figure 5. The paths page in the z/OS Connect Designer