My app team is trying to create a CICS call to an external API Server.  They are having issues getting a swagger doc created for the external API.  Is that documented anywhere about how to create this document.  Futher, is it a requirement to have the swagger doc to access the  external API we have lots of api's with no swagger doc.

------------------------------
garrett shaw
------------------------------

Technically speaking you could ask for an OpenAPI specification if your colleagues/counterparts are having trouble finding "Swagger." (Swagger is one tool among many that deals with OpenAPI specifications.) Exactly how they generate and provide OpenAPI specifications to you depends on what sort of API system/middleware they're using. If you happen to know what that is, it's possible someone may be able to provide a more specific pointer.

While having an OpenAPI specification makes access to an API quicker and easier, z/OS Connect Enterprise Edition does not require them. You can still define that remote API in the z/OS Connect EE tooling as long as you have enough alternative information about it.

------------------------------
Timothy Sipples
------------------------------

Hello @Timothy Sipples,

Can you please explain what you mean by - ​While having an OpenAPI specification makes access to an API quicker and easier, z/OS Connect Enterprise Edition does not require them. You can still define that remote API in the z/OS Connect EE tooling as long as you have enough alternative information about it.


Do you mean it's possible to create the .ara file without an OpenAPI specification?


------------------------------
Rahul
------------------------------

Original Message:
Sent: Mon November 23, 2020 10:58 PM
From: Timothy Sipples
Subject: Calling an external API server from CICS

Technically speaking you could ask for an OpenAPI specification if your colleagues/counterparts are having trouble finding "Swagger." (Swagger is one tool among many that deals with OpenAPI specifications.) Exactly how they generate and provide OpenAPI specifications to you depends on what sort of API system/middleware they're using. If you happen to know what that is, it's possible someone may be able to provide a more specific pointer.

While having an OpenAPI specification makes access to an API quicker and easier, z/OS Connect Enterprise Edition does not require them. You can still define that remote API in the z/OS Connect EE tooling as long as you have enough alternative information about it.

------------------------------
Timothy Sipples
------------------------------

If you have an API (on z/OS or elsewhere) that you'd like to access from z/OS Connect Enterprise Edition but that doesn't have an OpenAPI definition file, then likely the fastest, easiest way to access that API is to generate an OpenAPI description file which you then use with the z/OS Connect EE toolkit to generate the .ara deployment file. There are a lot of tools that can generate the API description file for you. One example is Swagger Inspector, but there are many others. (If you happen to have IBM App Connect Enterprise, IBM Integration Bus, or IBM Cloud Pak for Integration then I believe its tools can help.) Of course you have to know something about how to access the API, even if it's not Swagger/OpenAPI defined.

------------------------------
Timothy Sipples
------------------------------

Original Message:
Sent: Wed March 03, 2021 12:39 PM
From: Rahul
Subject: Calling an external API server from CICS

Hello @Timothy Sipples,

Can you please explain what you mean by - ​While having an OpenAPI specification makes access to an API quicker and easier, z/OS Connect Enterprise Edition does not require them. You can still define that remote API in the z/OS Connect EE tooling as long as you have enough alternative information about it.


Do you mean it's possible to create the .ara file without an OpenAPI specification?


------------------------------
Rahul
------------------------------


Original Message:
Sent: Mon November 23, 2020 10:58 PM
From: Timothy Sipples
Subject: Calling an external API server from CICS

Technically speaking you could ask for an OpenAPI specification if your colleagues/counterparts are having trouble finding "Swagger." (Swagger is one tool among many that deals with OpenAPI specifications.) Exactly how they generate and provide OpenAPI specifications to you depends on what sort of API system/middleware they're using. If you happen to know what that is, it's possible someone may be able to provide a more specific pointer.

While having an OpenAPI specification makes access to an API quicker and easier, z/OS Connect Enterprise Edition does not require them. You can still define that remote API in the z/OS Connect EE tooling as long as you have enough alternative information about it.

------------------------------
Timothy Sipples

this link

https://www.ibm.com/support/knowledgecenter/SS4SVW_3.0.0/facilitating/build_toolkit_prop.html

describes what properties can be specified when creating the property file that you then use to create the ara file to use when CICS is calling an API

in above link says this is a mandatory fiield

apiDescriptionFile

Specify the location and name of the JSON or YAML Swagger document to be used to generate the data structures, API information file, and an API requester archive file. The Swagger file is not required to have a particular file type extension; the file contents dictate the file format. For more information about the Swagger files supported and the artifacts generated, see Using the build toolkit to generate artifacts for an API requester.

which means you will need a swagger file to use an input

there is no doc in the zCEE knowledge center about how to create the swagger file, it is expected that whoever is providing the API will provide you the swagger file, or you will have to create it yourself

------------------------------
Edward McCarthy
WAS on System z
------------------------------