Using the API provider Gradle plug-in

The IBM® z/OS Connect API provider Gradle plug-in generates artifacts from an OpenAPI 2.0 document or an OpenAPI 3.0 document to call APIs from your z/OS applications.

1. Create a project directory with a name of your choice.
   For example, api-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 API provider Gradle plug-in statement to it. The following code example references version 1.5.0 of the API provider Gradle plug-in. Update the version number in the code example from 1.5.0 to match the version of the API provider Gradle plug-in you're using.

   plugins {
     id 'com.ibm.zosconnect.gradle' version '1.5.0'
   }
   repositories {
     maven {
       url '/templates/gradleLibs/'
     }
     mavenCentral()
   }

   Optional: With this configuration step, Gradle loads dependencies from a local directory or Maven Central. To use Maven repository hosted internally within your network, update the build.gradle file by adding the relevant repositories to the repositories section.

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

   pluginManagement {
      repositories {
          maven {
             url '/templates/gradleLibs/'
          }
          gradlePluginPortal()
      }
   }

   With this configuration step, Gradle loads plug-ins from a local directory or the Gradle plug-in portal. To use Maven Central or a Maven repository hosted internally within your network, update the settings.gradle file by adding the relevant repositories to the pluginManagement repositories section.
3. Use the following Gradle command to generate the directory structure and options.yaml file. From your project directory, run the following command:

   gradle apiProviderLayout

   This command creates the required API project directory structure inside the selected directory.

4. Copy your OpenAPI 2.0 document or the OpenAPI 3.0 document into the src/main/api subdirectory.

   The API provider supports an OpenAPI document that consists of a single file that is named openapi.yaml, openapi.json, or swagger.json. The directory structure should look like this:

   +-- api-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 creates the file but fails with message BAQG0008E because you must supply a value for the required parameter program. For more information about these supported properties, see The API provider Gradle plug-in properties and options for CICS.

   The options.yaml file must specify the mandatory provider, programInterface, language, connectionRef, program, and ccsid properties. Edit the values and add other optional properties as required for your API. For more information about supported properties, see The API provider Gradle plug-in properties and options for CICS.
6. Generate the API provider language structures. From the project directory, run the following Gradle command:

   gradle generateApiProvider --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 are generated by the Gradle plug-in. The z/OS Assets, one for each operation in the OpenAPI document, will all share the same program value. 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.

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

   gradle generateCopybooks --info