Enhancing a simple OpenAPI 3.0 document

A step by step how-to tutorial to enhance a simple OpenAPI 3.0 document to import to z/OS® Connect Designer.

Before you begin

zosConnect-3.0 Applies to zosConnect-3.0.

Open the Swagger Editor on a web browser of your choice. Type editor.swagger.io in the address bar.

editor.swagger.io

About this task

This how-to tutorial provides a step by step guide to enhancing the EmployeesApi created in the previous tutorial Creating a simple OpenAPI 3.0 document that integrates with Db2® using the online Swagger Editor. Use the following video as a reference while you work through the steps.

Note: All the steps in the tutorial need to be completed in order.

If you didn’t complete the Creating a simple OpenAPI 3.0 document tutorial, use the following steps.

Go to https://github.com/zosconnect/test-samples/tree/main/oas .
Click EmployeesApiStarter.yaml file and then click the Raw button in the upper right of the file view.
Paste the Raw format of the EmployeesApiStarter.yaml into the editor panel of the Swagger Editor.

Screen capture to show the EmployeesApiStarter.yaml in the Swagger Editor — Figure 1. EmployeesApiStarter.yaml in the Swagger Editor

The sections in this tutorial are as follows where each section builds on the previous section. Remember to ensure all the steps from the previous section are completed before you start on the next one.

Creating re-usable components
Add a PUT operation
Using the enhanced EmployeesAPI with z/OS Connect Designer

Procedure

Creating re-usable components.

Note: The component: object allows the definition of reusable components to reference throughout the OpenAPI document.

Define the "500" reusable response object for returned errors as a component.
Type "500": after the properties of the "200" response object and add the mandatory description for the "500" response object on the following line.
```
 "500":
          description: Internal Server Error
```
Note: Define the "500" response object at the same indentation as the "200" reusable response object.
Define the content object by typing content: on the next line and define the MIME type.
For example,
```
content:
            application/json:
```
Note: IBM® z/OS Connect currently supports the JSON format only.
Define the schema: object of what to expect back from the "500" response by typing schema: on the next line.
In this tutorial, we define the response as an object with a single property of a message: of type: string with an example of a message describing the error.
For example,
```
schema:
              type: object
              properties:
                message:
                 type: string
                 example: "A message describing the error."
```
Define a component: object at the same level as the paths, servers, info, and openapi objects.

The component: object allows the definition of re-usable components that can be referenced throughout the OpenAPI document. In this tutorial, we reuse the employee structure that was built in the "200" response.

Within the component: object, create a new schema object and within this object, add a new object called EmployeeBody.
For example,
```
components:
 schemas:
  EmployeeBody:
   type: object
   properties:
    EmployeeNumber:
      type: string
      example: "000150"
    firstName:
     type: string
     example: "BRUCE"
    lastName:
      type: string
      example: "ADAMSON"
    salary:
      type: number
      example: 25280
```
Define a generic ErrorResponse object by typing ErrorResponse: at the same level as the EmployeeBody object within the schemas object.
Copy and paste the following from the response 500 object to the new ErrorResponse object.
```
  ErrorResponse:
    type: object
    properties:
     message:
      type: string
      example: "A message defining the error."   
```
View the updated API Schemas structure in the Swagger Editor.

Figure 2. Updated API schemas
Note: The schema for employeeBody and ErrorResponse in Figure 2 are expanded by using the .
Reference the schemas in Step 4 and Step 6 as reusable components with the Reference $ref: object.
- For the Response 500, delete the definition from type: object to example: "A message describing an error" as shown and replace with an ErrorResponse Reference $ref: object.
  Figure 3. Response 500 - type object code for deletion
  The ErrorResponse Reference $ref: object needs a reference path that includes components/, schemas/ and the ErrorResponse object as shown.
```
$ref: '#/components/schemas/ErrorResponse'
```
- For the Response 200, delete everything within the properties object for the response 200 object as shown and replace with an EmployeeBody Reference $ref: object.
  Figure 4. Response 200 - type object code for deletion
  The EmployeeBody Reference $ref: object needs a reference path that includes components/, schemas/, and the EmployeeBody object as shown.
```
$ref: '#/components/schemas/EmployeeBody'
```
Note: The object path in the reference path is prefixed with # and / and is always within single quotation marks ' '.
An example of the updated API definition is shown in Figure 5.
Figure 5. API schemas with Reference objects
To verify your updates with the reference $ref: object for GET /employees, click to view the Parameters. See that the Example Value for the Response 200 and the Response 500 are the same as previously entered.
Figure 6. Swagger Editor $ref: object example

Add a PUT operation.

Add the following as the paths parameter to be used as the id to match the employee record.
Under the Paths object, add the following.
```
  /employees/{id}: 
```
Note: Add this new paths parameter at the same indentation level as /employees:
Figure 7. Add employees/{id} path parameter

Add a put method and a mandatory description of the operation.

    put:
      description: Uses the updateEmployees Db2 z/OS asset

Define the parameters for the PUT method as we need to describe the {id} in the path.
Add the parameters: object. The parameters: object needs a name that is entered as -name: id. It's located in the path and for this case, required is true as you can't update an employee record without this path parameter.
```
      parameters:
      - name: id
      in: path
      required: true
```
Add the schema: keyword to define the schema object with type: of string with an example: of "000150".
```
       schema:
          type: string
          example: "000150"
        
```
Add the requestBody: object so we can pass in the updated information of the employee on the request body.
To do this, define the content object by typing content: on the next line and define the MIME type.
```
      requestBody:    
        content:
          application/json:
```
Next is to define the schema and use the EmployeeBody reusable component from earlier in the tutorial.
```
schema:
              $ref: '#/components/schemas/EmployeeBody'
```
Figure 8. /employees/{id} PUT operation
Add the responses object.

Note: Add the responses object at the same indentation level as the requestBody:
1. "200" - - For the case where the employee record is been successfully updated.
  
  Add the "200" response object with a description.
  
  Add the content object with the application/json object.
  
  Add the schema object with the EmployeeBody reference component.
```
     responses:
        "200":
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeBody'
```
2. "404" - For the case where we don't find the employee record we'd like to update.
  
  Add the "404" response object with a description.
  
  Add the content object with the application/json object.
  
  Add the schema object with the ErrorResponse reference component defined in the "500" response.
```
     responses:
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
```
3. "500" - For the case where there in an Internal Server Error.
  
  Add the "500" response object with a description.
  
  Add the content object with the application/json object.
  
  Add the schema object with the ErrorResponse reference component defined in the "500" response.
```
     responses:
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
```
  Figure 9. /employees/{id} PUT responses
View the rendered version of the file in the right side of the screen. Open the PUT /employees operation by using the .
- You can see a successful reference to the EmployeeBody on the request.
  Figure 10. Successful PUT operation request body
- See the correct references for the 200, 404, and 500 responses.
  Figure 11. Successful PUT operation responses
You can download this OpenAPI document straight from the swagger editor. Click File and then Save as YAML.

Figure 12. Swagger Editor - Save as YAML

Using the enhanced EmployeesApi with z/OS Connect Designer.

Switch browser tabs to one with z/OS Connect Designer started.
Figure 13. z/OS Connect Designer launch
For more information, see Starting and stopping IBM z/OS Connect Designer.
Find your downloaded EmployeesApi file on your machine.
Drag your EmployeesApi file into the z/OS Connect Designer file up-loader.
You are able to see EmployeesApi, version 0.1 with a description of Employee management API for Db2.
Figure 14. Importing EmployeesApi to IBM z/OS Connect Designer
Click Create API.
z/OS Connect Designer opens the Information page for the EmployeesAPI.
Figure 15. EmployeeApi Information page in IBM z/OS Connect Designer
Explore the EmployeesApi Paths in the z/OS Connect Designer Information navigation panel.
Click Paths /employees/{id} to view the operation properties for the EmployeesApi PUT operation. See the 200, 404, and 500 responses as defined in the Swagger Editor.

Figure 16. EmployeesApi PUT operation in IBM z/OS Connect Designer
Click each of the responses to view the structure.
For example, click the 200 response.
In the Edit Mapping tab, you can view the EmployeeBody component that contains EmployeeNumber:, firstName:, lastName:, and salary: that was created in 4
Figure 17. 200 response Employee Body in IBM z/OS Connect Designer

In the View structure tab, open the Body structure by clicking the . Then, click the next to the Reference object, in this case " $ref: '#/components/schemas/EmployeeBody' " to see the structure as defined in the EmployeesApi.

Figure 18. "200" response body structure
Check EmployeesAPI into source control.
For more information about Source Code Management, see Checking your IBM z/OS Connect API project into source control

Results

In this tutorial, EmployeesApi is now enhanced with some more advanced features and then reviewed those features in the z/OS Connect Designer.

A ready to download copy of EmployeesApi with the completed steps from this and the previous tutorial is available on GitHub at A launch icon to indicate a link opens a new tab or window. test-samples/oas/EmployeesApiBasic.yaml