Using the build toolkit to generate artifacts from the Swagger file

Run the build toolkit command line interface (CLI) to generate artifacts for the API requester.

About this task

For this scenario, we use the CLI of the build toolkit to generate all the artifacts to enable the client CICS® application to call the catalog manager API. These artifacts include an API requester archive (.ara file) and a summary report for the catalog manager API, and API information files, data structures and logs for each operation in the API. In this task, you will use the build toolkit to create these artifacts from the catalogManager.json Swagger file that is obtained in the prerequisite task. For more information, see Using the build toolkit to generate artifacts for an API requester.

Diagram of usng the build toolkit to generate artifacts

Procedure

  1. Create a local directory called buildToolkit under the /u/{userid} directory.
  2. Copy the build toolkit compressed file, zconbt.zip as a binary file, from the product installation directory and extract the zconbt.zip file to the buildToolkit directory.
  3. Create directories and data sets for the artifacts to be generated.
    1. Create a directory called apiReqScenario under the /u/{userid} directory to store the catalogManager.json file.
    2. Create a directory called archives under the apiReqScenario directory to store the generated API requester archive and summary report.
    3. Create a directory called logs under the apiReqScenario directory to store the generated log file for each operation that is defined in the API.
    4. Create a data set on MVS™ to store the generated API information file and data structures, for example, TEST.CATALOG.COBOL.
  4. Upload the catalogManager.json file, as a binary file, to the apiReqScenario directory.
  5. Create a local properties file named catalogManager.properties and enter the directory or data set names and other attribute values:
    
    apiDescriptionFile=../apiReqScenario/catalogManager.json
    dataStructuresLocation=TEST.CATALOG.COBOL
    apiInfoFileLocation=TEST.CATALOG.COBOL
    connectionRef=RemoteAPIconn
    logFileDirectory=../apiReqScenario/logs
    language=COBOL
  6. Upload the catalogManager.properties file, as a binary file, to the apiReqScenario directory.
  7. Enter the buildToolkit directory and enter the zconbt.zos command:
    
    ./bin/zconbt.zos --properties ../apiReqScenario/catalogManager.properties --file ../apiReqScenario/archives/catalogManager.ara
        
  8. When processing of the command is completed, a message is returned, indicating whether the artifacts were built successfully. If any errors occur, make the necessary corrections and repeat the procedure.

Results

Several artifacts for the API requester are created in the directories as you have configured. For each API, an API requester archive (.ara) file and a summary report are generated. For each API operation, an API information file, request data structures, and response data structures are generated. The following table shows the directory structure (/ data set) and contents created:
Table 1. Directory paths (/ data sets) and contents
Path (/data set) Contents
./apiReqScenario/
  • Directory archives
  • Directory logs
  • catalogManager.properties
  • catalogManager.json
./apiReqScenario/archives
  • catalogManager.ara: the API requester file that can be deployed to the IBM® z/OS® Connect server.
  • catalogManager-summary.txt: the summary report that contains information about all the data structures and API information file.
./apiReqScenario/logs Logs for each operation defined in the catalogManager.json file:
  • getInquireCatalog.log: the log file for the getInquireCatalog operation
  • getInquireSingle.log: the log file for the getInquireSingle operation
  • postPlaceOrder.log: the log file for the postPlaceOrder operation
TEST.CATALOG.COBOL
  • API00I01.cbl: the API information file of the getInquireCatalog operation
  • API00P01.cbl: the response data structure of the getInquireCatalog operation
  • API00Q01.cbl: the request data structure of the getInquireCatalog operation
  • API01I01.cbl: the API information file of the getInquireSingle operation
  • API01P01.cbl: the response data structure of the getInquireSingle operation
  • API01Q01.cbl: the request data structure of the getInquireSingle operation
  • API02I01.cbl: the API information file of the postPlaceOrder operation
  • API02P01.cbl: the response data structure of the postPlaceOrder operation
  • API02Q01.cbl: the request data structure of the postPlaceOrder operation