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

zosConnect-3.0 Applies to zosConnect-3.0.

Containers Applies to z/OS Connect container deployments.

Make sure that all prerequisite tasks are complete:

Prepare the sample CICS application.
Downloading the CICS API project sample.
Downloading the z/OS Connect Designer image.
Create the CICS tutorial workspace using Docker Desktop.
Configure IPIC connections to CICS 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

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 CatalogManagerApi.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.100          “/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. Allow 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. 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.
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 CatalogManagerApi, logs, and certs directories mounted to this running container.
Import the OpenAPI definition, CatalogManagerApi.yaml for the Catalog Manager API into your API project.

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

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

Note: You can review and edit the CatalogManagerApi.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 CatalogManagerApi.yaml. Warning indicators in the navigation panel window show where your input is needed. Paths are endpoints (resources) that your API exposes, such as /items/{id} or /items 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