It is common practice to use Swagger(OpenAPI) descriptor files when integration of API or RESTful service with another systems. For example, new REST Service Broker in K2 Blackpearl 4.7 for integration with REST services uses Swagger descriptors when Service Instance for specific service is created. Data and behavior of the REST services are generated on basis of provided Swagger file. In my case, I wanted to use data retrieved from SharePoint Search with REST broker and display in K2 SmartForm. Here is the approach I took, which is based on official step-by-step guide from K2 https://help.k2.com/kb001758

Auhenticate to SharePoint Online

Call Search endpoint using Fiddler Composer

Use RESTUnited to Generate and Export Swagger definition

Clean up generated definition with Notepad++

Authenticate to SharePoint Online

We need to authenticate to SharePoint Online first. That will ensure that our calls that we make to the search API are authenticated and that the response we receive is useful to RESTUnited REST Wizard. We can now start Fiddler and configure it to watch traffic from current web browser process and then perform call to Search API from the browser – that we will use later as a template for our call from Fiddler composer.

Call Search endpoint using Fiddler Composer

To get the example response from service, our next step is to reply a call to Search query endpoint from Fiddler Composer. Easiest way to do that is to use “Replay” – > “Reissue from Composer” command in Fiddler, and to modify Accept header so that we receive JSON response instead of XML.

We will use “odata=nometadata” option to receive minimal payload back from the service which will simplify our data model in Swagger. Excellent article that describes JSON Light support in SharePoint Online is available on Office Blogs.

After re-issuing the request, we will verify that the call succeeded (receiving Response Code 200) we will have to decode the response so that we get proper JSON that will be used in next step.

Now we can take JSON Body of the response and copy it to text file, as we will need it in RESTUnited

Use RESTUnited to generate and export Swagger definition

RESTUnited is web based SDK Generator that we can use to generate client SDKs for web services. It supports most popular languages and platforms. But, more important for our case is that we can use REST API Wizard to create and export Swagger descriptor file for our web service. Even free account on RESTUnited is enough to use REST Wizard.

After login, we start New REST API Wizard to create definition of our service.

In the first step we enter

Endpoint method and URL

Base URL for the service

Example response gathered in previous step

In next step we define query endpoint and parameters. In our case, we use only querytext parameter, which is required. If we would need to use any of the optional query parameters that are allowed in Search REST API, we would add it here. Good overview of Search REST API is available on MSDN

In Step 3 we can customize response type. In this case, we will just use default/recommended values from the wizard.

Next, we have an option to test the service. However, we will not do it now because the call would not be authenticated. We model only basics of the service, without passing auth token – as we will do that from the service consumer application.

In final step, we will export Swagger definition

Clean up generated definition with Notepad++

Generated swagger file is quite big and difficult to read.

As a final step, we will use Notepad++ to clean up generated Swagger file, to make it more readable. This step includes:

Removing “examples” property and its value

Removing all values assigned to “x-example” property in Swagger

Formatting document to make it human readable

We will use brace matching feature in Notepad++ (Ctrl+Alt+B). End result will look like this