IBM Z and LinuxONE - IBM Z - Group home

One of the key features that was added to IBM Cloud Provisioning and Management PTFs (UI55996 and UI56001) in 2Q 2018 is the use of Swagger to document and present the associated REST APIs in an easily consumable format. With this addition, cloud architects can easily view the constructs of the Cloud Provisioning and Management REST APIs so that enabled z/OS subsystems can be incorporated into their cloud offering.

Swagger is a framework of developer tools for developers writing application programming interfaces (APIs) that adhere to the OpenAPI Specification (OAS). Formerly known as the Swagger Specification, OAS is a format for describing REST APIs. Swagger consists of two main functions, the Swagger UI and the Swagger Codegen. Together, these powerful tools allows you to document, as well as drive, APIs. Swagger generates the UI by reading a .json or a .yaml file that describes each endpoint of the API you want to document. One way to generate the UI is to simply write the information describing the APIs and their properties in a .json or .yaml file with the correct syntax. The other way is to add Swagger-specific annotations to the actual API code. Swagger Codegen scans the annotations and creates a .json or .yaml file for Swagger to read. Swagger supports a multitude of code languages, including Javascript, Haskell, Java, Python, and C#.

Swagger is pre-installed and enabled on the z/OSMF Liberty Server. In order to successfully access the Swagger UI, the user may need to configure additional security for z/OSMF. Refer to z/OSMF Programming Guide for details. Supplying the appropriate values for host name and port, use this address in a browser: “https://

APIs in the Swagger UI are organized based on the Cloud Provisioning and Management functions, such as the Published Software Catalog (PSC), Resource Management (RM), etc. Here is an example of the Swagger UI for the PSC:

The primary purpose of the Swagger UI is to display API documentation. This includes the model of the request body that the API expects, as well as the response body it will return upon completion. Swagger will show a description of each property defined by the API. Another function of the Swagger UI is its ability to drive the APIs. This greatly simplifies and speeds up development and testing. Here is an example of what the UI looks like to a user that is trying to submit a request.

Submitting an API request through the UI is very easy; just input any required information into the boxes, and then click the “Try it out” button. A real request will then be sent to the server, and the response will be displayed in the UI, as shown in this example:

The Swagger UI allows a cloud architect to easily view, interact with, and understand the constructs of the Cloud Provisioning and Management APIs, and can more easily incorporate z/OS into their cloud offering.