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