Swagger Definition File Creation

[ExCessna]

I have an app developed under Project Siena that was retrieving results through an API service. The connection to the API was made using the WADL generator provided by the Project Siena Team. I understood it and found it easy to use to connect to API services. When I load this Project Siena App into PowerApps, the app still recognizes the API connection and can even retrieve results (slowly). At some point in the app's use, however, a notification appears that the connection is no longer supported and has been removed and subsequently, the app can no longer retrieve results.

I have tried to understand how to create a Swagger file from the resources provided in "Get Help Creating Swagger Files" under What are custom APIs. However, I'm not getting it and it is a major roadblock to my progress in using PowerApps. So:

1. Is there a way to convert the known working Project Siena WADL file to a Swagger Definition File? I've tried using Convertron - API Transformer without success. When I load the Siena WADL file and click "Transform", I receive an error message "There is an error in XML document (53, 47)". I have no idea what that means and I can't seem to find instructions on how to use Convertron.
2. Is there a resource with at least one example for an absolute beginner to Swagger? I'm just not getting it yet. I understand Swagger is the standard but WADL using the generator was so much easier.

Understanding how to create Swagger files would go a long way to reaching my goals with PowerApps. It is a great tool but dealing with Swagger seems very complicated right now. Any help would be very much appreciated.

[Anonymous]

Have a look at http://editor.swagger.io/

This can import existing Swagger in YAML/JSON format and validate it to make sure there arent any problems.

Once its validated there, it should work with the custom API tool in PowerApps.

I hope this helps,

Matt

[ExCessna]

I didn't realize the swagger.io editor would import a WADL file. So I may be a little further down the road to a solution. However, I receive the following error, so I will try to validate the file and report back. As I said, I'm completely new to swagger, so it may take me a while. Thank you for your help.

Here's the error:

Unknown Error

obj must be an Array or an Object

Jump to line

Details

Object

message:"obj must be an Array or an Object"

code: "UNCAUGHT_SWAY_WORKER_ERROR"

level: 900

type: "Unknown Error"

description:"obj must be an Array or an Object"

It indicates the error is in line 32 (indicated in Bold and enlarged type below) of the following code:

<?xml version="1.0" encoding="utf-16"?>
<application xmlns:siena="http://schemas.microsoft.com/MicrosoftProjectSiena/WADL/2014/11" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:sienatool="http://www.todo.com" siena:serviceId="BookByISBN" xmlns="http://wadl.dev.java.net/2009/02">
<grammars>
<siena:jsonTypes targetNamespace="http://www.todo.com" xmlns:wadl="http://wadl.dev.java.net/2009/02">
<siena:object name="ISBNSearch_Root">
<siena:property name="index_searched" type="string" />
<siena:property name="data" typeRef="ISBNSearch_data_Array" />
</siena:object>
<siena:object name="ISBNSearch_data_Object">
<siena:property name="title_long" type="string" />
<siena:property name="dewey_normal" type="string" />
<siena:property name="edition_info" type="string" />
<siena:property name="awards_text" type="string" />
<siena:property name="urls_text" type="string" />
<siena:property name="subject_ids" typeRef="StringArray" />
<siena:property name="title" type="string" />
<siena:property name="marc_enc_level" type="string" />
<siena:property name="author_data" typeRef="ISBNSearch_author_data_Array" />
<siena:property name="physical_description_text" type="string" />
<siena:property name="summary" type="string" />
<siena:property name="lcc_number" type="string" />
<siena:property name="book_id" type="string" />
<siena:property name="title_latin" type="string" />
<siena:property name="publisher_id" type="string" />
<siena:property name="publisher_text" type="string" />
<siena:property name="language" type="string" />
<siena:property name="isbn10" type="string" />
<siena:property name="publisher_name" type="string" />
<siena:property name="dewey_decimal" type="string" />
<siena:property name="isbn13" type="string" />
<siena:property name="notes" type="string" />
</siena:object>
<siena:array name="StringArray" type="string" />
<siena:object name="ISBNSearch_author_data_Object">
<siena:property name="name" type="string" />
<siena:property name="id" type="string" />
</siena:object>

...(code continues)...

[Anonymous · Accepted solution]

Im sorry ExCessna,

I didnt realise you already had the WADL file - editor.swagger.io does not import WADL - I've edited my post to correct myself.

WADL is what the PowerApps CustomAPI functionality eventually uses behind the scenes - they only need swagger to generate WADL again - so this means you need to reverse engineer your WADL file back to Swagger, just so they can convert it back to WADL again!

Unless the PowerApps team provide a way to describe an API using WADL, the only option is to convert somehow.

Looking at the XML, I dont fancy your chances as it looks like the sienna namespace, where your objects properties are defined, is a proprietry one, and not one that a standard WADL parser would understand.

You mentioned in your post that it was working - how did you manage to import this WADL file to begin with?

Thanks,

Matt

[ExCessna]

Matt,

The WADL file was generated for the app when it was first developed in Project Siena. It worked well. The app was then brought into PowerApps and, when the app is run, I am able to access the API using the API data connection that uses the WADL file. However, somewhere into its usage, PowerApps indicates it has removed the data connection because it is no longer valid. Actually, I have other apps with the same issue: an api connection that can't be restored permanently because I need to develop a Swagger file. 

It's interesting that WADL is used behind the scenes in PowerApps. I wondered why the Team suddently shifted to Swagger after providing a WADL generator in Project Siena. I understand why Swagger is preferred but the WADL generator made the use of custom APIs possible for people like me. Now I need to learn a lot more and I'm not sure where to begin, as I'm not even sure of what I don't know that I need to know before things will become clear again.

Thank you for your help, Matt. I will mark your reply as the answer, even though the reality is not what I had hoped for.

[Anonymous]

Hello ExCessna,

Yes, I'm afraid I dont know much about project Sienna.

Depending on how they make thier webservices, there may be another way.

If they make they're service endpoints using a tech called WCF, its possible that there may be another way to get a description, this time in another description language called WSDL.

I could take a look at the Sienna file if you are comfortable sharing it with me? 

If not, have a look for endpoint names (like https://sienna.microsoft.com/services/sienna.svc)

If you find one, you can check to see if it has a MEX endpoint by visiting the URL and adding ?wsdl on the end - its a long shot, but if they use WCF, and if they've enabled it, it mgiht be another format that you can try with the convertron tool you mentioned.

I hope this helps!

Matt

[ExCessna · Accepted solution]

Hi Matt,

Here's the entire WADL file, less the [app_key_here]:

<?xml version="1.0" encoding="utf-16"?>
<application xmlns:siena="http://schemas.microsoft.com/MicrosoftProjectSiena/WADL/2014/11" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:sienatool="http://www.todo.com" siena:serviceId="BookByISBN" xmlns="http://wadl.dev.java.net/2009/02">
<grammars>
<siena:jsonTypes targetNamespace="http://www.todo.com" xmlns:wadl="http://wadl.dev.java.net/2009/02">
<siena:object name="ISBNSearch_Root">
<siena:property name="index_searched" type="string" />
<siena:property name="data" typeRef="ISBNSearch_data_Array" />
</siena:object>
<siena:object name="ISBNSearch_data_Object">
<siena:property name="title_long" type="string" />
<siena:property name="dewey_normal" type="string" />
<siena:property name="edition_info" type="string" />
<siena:property name="awards_text" type="string" />
<siena:property name="urls_text" type="string" />
<siena:property name="subject_ids" typeRef="StringArray" />
<siena:property name="title" type="string" />
<siena:property name="marc_enc_level" type="string" />
<siena:property name="author_data" typeRef="ISBNSearch_author_data_Array" />
<siena:property name="physical_description_text" type="string" />
<siena:property name="summary" type="string" />
<siena:property name="lcc_number" type="string" />
<siena:property name="book_id" type="string" />
<siena:property name="title_latin" type="string" />
<siena:property name="publisher_id" type="string" />
<siena:property name="publisher_text" type="string" />
<siena:property name="language" type="string" />
<siena:property name="isbn10" type="string" />
<siena:property name="publisher_name" type="string" />
<siena:property name="dewey_decimal" type="string" />
<siena:property name="isbn13" type="string" />
<siena:property name="notes" type="string" />
</siena:object>
<siena:array name="StringArray" type="string" />
<siena:object name="ISBNSearch_author_data_Object">
<siena:property name="name" type="string" />
<siena:property name="id" type="string" />
</siena:object>
<siena:array name="ISBNSearch_author_data_Array" typeRef="ISBNSearch_author_data_Object" />
<siena:array name="ISBNSearch_data_Array" typeRef="ISBNSearch_data_Object" />
</siena:jsonTypes>
</grammars>
<siena:authenticationProviders />
<siena:template>
<siena:variable name="ApplicationKey" isSecret="true">
<siena:doc title="Application Key" />
<siena:modifyParams name="/book" attribute="fixed" format="{0}" />
</siena:variable>
</siena:template>
<resources base="http://isbndb.com">
<resource path="api/v2/json/[app_key_here]/book/9780849303159">
<method name="Get" id="ISBNSearch" siena:requiresAuthentication="false">
<request>
<param name="/book" required="true" style="Query" />
</request>
<response siena:resultForm="single">
<representation mediaType="application/json">
<param name="ISBNSearch_Name" type="sienatool:ISBNSearch_Root" style="Plain" path="" />
</representation>
</response>
</method>
</resource>
</resources>
</application> 

Sorry about the lead spacing. I don't know how to retain it in this post.

Hope this helps!

[Anonymous · Accepted solution]

Turns out the conversion tool you used doesnt like the "style" attribute on the Project Viena WADL.

I stripped it out, and tried it again.

It said "Success" and came back with this - it may not work out of the box, but its a good starting point for you:

{
"swagger": "2.0",
"info": {
"version": "",
"title": "Viena.xml",
"description": "",
"license": {
"name": "MIT",
"url": "http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT"
}
},
"host": "isbndb.com",
"basePath": "/",
"securityDefinitions": {},
"schemes": [
"http"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/api/v2/json/[app_key_here]/book/9780849303159": {
"get": {
"description": "",
"operationId": "Get_ISBNSearch_",
"produces": [
"application/json"
],
"parameters": [
{
"name": "/book",
"in": "query",
"required": true,
"x-is-map": false,
"type": "string",
"description": ""
}
],
"responses": {
"200": {
"description": ""
}
}
}
}
}
}

[ExCessna · Accepted solution]

Matt,

Yes, it works! I have the Custom Connection listed in the connections for my app. Now I will try to access the API using the connection.

Thanks for all your help!!

Update: The above worked to make a Custom Connection. It led me to look into Swagger in detail. I found the following links very helpful:

Writing Open API Swagger Tutorial

Swagger API with Query String

Parameters

In my case, the WADL-to-Swagger conversion output had to be modified to replace a "In: query" with an "In: path" parameter.