Creating Swagger descriptor file for SharePoint Search using RESTUnited, Fiddler and Notepad++

Update: Full post with details about SharePoint Search results in K2 is now posted http://www.dragan-panjkov.com/exposing-sharepoint-online-search-results-in-k2-smartforms

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

  1. Auhenticate to SharePoint Online

  2. Call Search endpoint using Fiddler Composer

  3. Use RESTUnited to Generate and Export Swagger definition

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

image

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.

image

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.

image

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.

image

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

image

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.

image

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

image

In the first step we enter

  • Endpoint method and URL

  • Base URL for the service

  • Example response gathered in previous step

image

image

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

image

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

image

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.

image

In final step, we will export Swagger definition

image

image

Clean up generated definition with Notepad++

Generated swagger file is quite big and difficult to read.

image

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

image

Full Swagger file that can be used as starting point for your projects can be found in my GitHub repository https://github.com/panjkov/SwaggerDefs