Overview

This article is part 3 of a 4 part series, where I’ll cover editing of the Swagger definition file that we’ll import into NWC in part four in order to create the actual Nintex Xtension.  In part 1, I covered the steps to setup your Azure Functions and Visual Studio environment, and in part 2 I covered the C# code that was developed and published to Azure Functions.

In part 4, we’ll import our Azure Function into Nintex Workflow Cloud as a new Connector using NWC’s Xtensions framework.

Configure Methods

Before creating our API definition, we’ll need to configure the allowed HTTP methods for our new function, so that it only allows POST methods.  First, navigate to your new Function App in the Azure portal, expand the Functions section, then expand the specific function and click on the Integrate option in the portal, as shown below:

image

From the Integrate screen, review the Trigger configuration and find the Allowed HTTP methods drop down field, which may be defaulted to a value of All methods.  Change it to Selected Methods instead and then uncheck all of the HTTP methods except for POST, as shown below:

image

Now that the allowed methods are set, we can create our Swagger API Definition.

Swagger Definition

Creating a Swagger Definition was a new experience for me and there are various tools out there that can help with the process.  One tool is built into the Azure Functions portal site, and that is primarily where I created my definition.  But you can also use the native editor at http://editor.swagger.io/.  Although both editors are very similar, there were a few things that I found easier to figure out on the Swagger site than in the Azure Portal, so I used both of them.  But we’ll start in the Azure Portal.

Regardless of the editor that you use, you create your swagger definition using a language call YAML, which stands for “YAML Ain’t Markup Language”.  Instead its described as a “a human friendly data serialization standard for all programming languages”.  The output of a Swagger definition is JSON, but you edit with YAML.

To generate the API definition for your Azure Function:

Navigate to your Function App in Azure Portal, and click on the API Definition link.

image

This will display the Function API definition (Swagger) page.  For API definition source, click on the Function (preview) button.

image

This will display the Swagger Editor, with a blank definition, as shown below:

image

Click on the button for Generate API definition template.image

This will generate a boilerplate API definition based on the metadata about your function, as shown below.  As you edit the swagger definition, it will validate your changes and provide error details in real time.

image

Here is what the completed API Definition looks like for my GsaPerDiemFunctions app:

image

To review the generated Swagger JSON, click the Copy button next to the API Definition URL:

image

Then test it in your browser, or better yet a REST client tool like Postman.  The resulting JSON should look like this:

{
    "swagger": "2.0",
    "info": {
        "title": "gsaperdiemfunctions.azurewebsites.net",
        "version": "1.0.0"
    },
    "schemes": [
        "https"
    ],
    "host": "gsaperdiemfunctions.azurewebsites.net",
    "basePath": "/api",
    "paths": {
        "/GetPerDiemByZip?code={APIKEY}": {
            "post": {
                "tags": [
                    "Looks up GSA Per Diems for Hotel and Meals by Date and Zipcode."
                ],
                "summary": "Looks up GSA Per Diems for  Hotel and Meals by Date and Zipcode.",
                "operationId": "GetPerDiemByZip",
                "x-ntx-summary": "Looks up GSA Per Diems for Hotel and Meals by Date and Zipcode.",
                "parameters": [
                    {
                        "name": "APIKEY",
                        "in": "path",
                        "description": "The API Key",
                        "x-ntx-summary": "The API Key",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "GsaPerDiemInput",
                        "in": "body",
                        "description": "Contains Zipcode and Tripdate.",
                        "x-ntx-summary": "Contains Zipcode and Tripdate.",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/GsaPerDiemInput"
                        }
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "consumes": [
                    "application/json"
                ],
                "responses": {
                    "200": {
                        "description": "Returns Per Diem Amounts for Hotel and Meals by Zip and TripDate",
                        "schema": {
                            "$ref": "#/definitions/GsaPerDiemOutput"
                        }
                    }
                },
                "security": [
                    {
                        "apikeyQuery": []
                    }
                ]
            }
        }
    },
    "securityDefinitions": {
        "apikeyQuery": {
            "type": "apiKey",
            "name": "code",
            "in": "query"
        }
    },
    "definitions": {
        "GsaPerDiemInput": {
            "description": "Zipcode and tripdate for the trip",
            "properties": {
                "Zip": {
                    "type": "string",
                    "description": "Zipcode for main destination of the trip"
                },
                "TripDate": {
                    "type": "string",
                    "description": "Date of the first day of the trip"
                }
            },
            "required": [
                "Zip",
                "TripDate"
            ]
        },
        "GsaPerDiemOutput": {
            "description": "Max Per Diem amounts for Meals and Hotel",
            "properties": {
                "Hotel": {
                    "type": "integer",
                    "description": "Per Diem amount allowed for Hotel"
                },
                "Meals": {
                    "type": "integer",
                    "description": "Per Diem amount allowed for Meals"
                }
            },
            "required": [
                "Hotel",
                "Meals"
            ]
        }
    }
}

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s