Using the API provider Gradle plug-in

The IBM® z/OS Connect API provider Gradle plug-in generates artifacts to host APIs that expose your CICS® COBOL channel and container applications.

1. Create a project directory with a name of your choice, for example api-provider-project.
   Note: The project directory name and the full path leading up to that directory must not contain invalid URI characters such as spaces.

   In that directory, create a build.gradle file and add the following content:

   /**************************
   * Copyright IBM Corp. 2021
   **************************/
   plugins {
     id 'com.ibm.zosconnect.gradle' version '1.3.0'
   }
   repositories {
     maven {
       url '/templates/gradleLibs/'
     }
     mavenCentral()
   }
   

2. Create a settings.gradle file in the project directory and add the following content:

   /**************************
   * Copyright IBM Corp. 2021
   **************************/
   pluginManagement {
      repositories {
          maven {
             url '/templates/gradleLibs/'
          }
          gradlePluginPortal()
      }
   }

3. Use the following Gradle command to generate the API provider project directory structure.

   gradle apiProviderLayout

4. Copy your OpenAPI definition into the src/main/api subdirectory.
   The API provider supports an OpenAPI definition that consists of a single file named openapi.yaml or openapi.json. The directory structure should look like this:

   +-- api-provider-project
     +-- src
       +-- main
         +-- api
           +-- openapi.yaml
         +-- config
         +-- liberty
         +-- operations
         +-- zosAssets
         +-- web.xml
     +-- build.gradle
     +-- settings.gradle

5. Create the options.yaml file in the src/main/config directory and specify the required properties.
   Tip: You can run the gradle generateApiProvider task to create the options.yaml file for you and populate it with the required properties and their default values. This task will create the file but will fail with message BAQG0008E because you must supply a value for the required parameter program.

   The options.yaml file must specify the mandatory provider, programInterface, language, connectionRef, program, and ccsid properties. You can add other optional properties that are needed. For more information about these supported properties, see The API provider Gradle plug-in generator options.
6. Use the following Gradle command to generate the API provider project files and the request and response language structures for each operation.

   gradle generateApiProvider --info

   Alternatively use the following Gradle command to generate the request and response language structures for each operation.

   gradle generateCopybooks --info

   Use the --info option to get more diagnostic information in the Gradle output and the OpenAPI Parser log files that are generated in the build/logs/zosConnectProvider directory.

The liberty, operations and zosAssets directories now contain the files that were generated by the Gradle plug-in. The z/OS Assets, one for each operation in the OpenAPI definition, will all share program. If you are planning to implement each operation as a different CICS®COBOL application, then you must edit the zosAsset.yaml for the operations and change the program value before the next step. You can also change the value of connectionRef in zosAsset.yaml if you want the operations and z/OS assets to go to different CICS regions.

7. Use the following Gradle command to build the API provider project and generate the API provider archive file.

   gradle build

   For more information, see Building z/OS Connect APIs with Gradle.