Creating a simple OpenAPI 3.0 document

A step by step how-to tutorial to create a simple OpenAPI 3.0 document for API integration.

1. Using a web browser of your choice, type editor.swagger.io in the address bar.

   editor.swagger.io

   Or, use the following link https://editor.swagger.io

   The Swagger Petstore - OpenAPI 3.0 sample loads. The API code editor is in the left panel and the Swagger Editor is on the right. The Swagger Editor displays a rendered version of the API defined in the code editor panel on the left.

   

2. Click the left panel and clear the contents.
   This tutorial creates a new API called EmployeesAPI from scratch. When you clear the contents in the code view, the Swagger Editor is updated to reflect no content in the file. See Figure 2.

   

   Tip: It is useful to have the OpenAPI 3.0.0 specification open to reference https://swagger.io/specification/. Click Specification and then Schema to view the format of valid objects within an OpenAPI document. The OpenAPI Object details the required fields as shown in Figure 3.

   

3. Type openapi: 3.0.0 as the first line in the blank file.

   openapi: 3.0.0

   Note: OpenAPI v3.0.0 is the current version that z/OS Connect supports.
   Errors appear in the Swagger Editor as seen in Figure 4. These errors are resolved as the OpenAPI 3.0 document is created with valid syntax.

   

4. Define the info object in the OpenAPI 3 definition by typing info: on the next line.
   The Info Object schema specification, as seen in Figure 5, states that title and version are required fields that must be added to the info: object.

   

   Type the following to complete the info: object.

   info:
       title: EmployeesApi
       description: Employee Management API for Db2.
       version: "0.1"
   

   Note: The description field is optional. We add it here so people that use the EmployeesAPI knows it purpose.
5. Define the servers object in the OpenAPI 3 definition by typing servers: on the next line. The server object represents a server by using the URL to the target host. Add a single URL to the server object with a forward slash /.

   servers:
       -   url: /

   Note: IBM® z/OS Connect uses the contextRoot to build the API. It is set to / and is configurable.
6. Define the paths object in the OpenAPI 3 definition by typing paths: on the next line.
   The paths object holds the relative paths to the individual endpoints and their operations. The path is appended to the URL from the servers object in order to construct the full URL.
   In this tutorial, we want to query a list of employee records for use in a front-end application. To do this, start by adding the employees path and then adding a get method on that path with a description. Type the following in your OpenAPI 3 definition.

   paths:
     /employees:
       get:
         description: Uses the getEmployees Db2 z/OS asset.
   

7. Define the responses: object by typing responses: on the next line.
   The responses object is a container for the expected responses of an operation that maps an HTTP response code to the expected response.

   Note: The responses: object must contain at least one response code that should be the response code for a successful operation. The response code must be in double quotation marks.
   For example, "200".
   In this tutorial, a "200" response is defined for a successful operation. Add a mandatory description.

         responses:
           "200":
             description: OK

8. Define the content object by typing content: on the next line and define the MIME type.
   In this tutorial, the application is JSON. IBM z/OS Connect currently only supports the JSON format.

             content:
               application/json:

9. Define the schema object for the "200" response by typing schema: on the next line.
   This tutorial receives a list of items: as an array so the schema type is defined as an array. Each item in the array has the same set of properties: as defined here:

   1. employeeNumber with type string for example "000150"
   2. firstName type string for example BRUCE

                 schema:
                   type: array
                   items:
                     properties:
                       employeeNumber:
                         type: string
                         example: "000150"
                       firstName:
                         type: string
                         example: "BRUCE"
                       lastName:
                         type: string
                         example: "ADAMSON"
                       salary:
                         type: number
                         example: "25280"

10. You can download this OpenAPI document straight from the swagger editor. Click File and then Save as YAML.

    

11. 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

If you have no errors in the OpenAPI 3.0.0 definition, explore the API in the Swagger Editor as seen in Figure 7 and Figure 8.

To explore the API in the Swagger Editor, expand the operation. In this tutorial, the operation is GET /employees that is a combination of the method and the path as now defined in the file.

Click as seen in Figure 7 to expand the GET /employees operation details.

For the GET /employees operation, you can see.

1. responses: with a value of "200" for a successful operation.
2. media type of application/json.
3. Data for each of the employees items returned in the array.

Tip: If you have errors, use the information in the Swagger Editor to identify and resolve the errors. Figure 4 provides a view of how the errors are displayed.