A group of API developers are creating API’s for BizTalk Server to consume and they keep on sending us their RAML API definitions to start our development. We use Azure APIM and like Swagger. This blog will show how we convert the RAML to Swagger and then import this into Azure API Management.
There is no support to import RAML directly into Azure APIM. Thus you have to create the Swagger from the RAML and then import the Swagger file into Azure APIM.
Restlet Studio
I have used Restlet studio for many years to create, view and edit Swagger and I love it when I work with API’s. Restlet Studio also allows you to import RAML and convert between RAML and Swagger.
The RAM document was a zip file that contains several folders and files including json file. There is file at the top level that references the json files as shown below. I do not know what application is generating the zip files. How am I going to put all this into a swagger definition file?
Answering this question is easy, one of the Restlet studio options is to import a RAML zip file. Importing the zip file pops up an option to choose the main file , api.raml.
Gratifingly the file imports with a few warnings. It is interesting that Reslet Studio tries to enforce REST standards i.e. a DELETE method should not return any content.
Furthermore on The documentation displayed in Reslet studio was also aesthetically pleasing,
With the RAML import in hand the next step was to export the file as Swagger. This processed without error and created a swagger file that we can import into APIM later. Furthermore exporting the file as RAML created just one definition file this time.
Azure API Management(APIM)
Finally the swagger was imported into APIM without error to give the same documentation that we saw in Restlet studio. See one of my previous post to see how to do this step.
In addition we have code snippets in many different languages, example requests, response and HTTP errors. In addition we have a button to get test requests.
In summary we have been able to convert RAML to Swagger that can be imported in to APIM. I am happy because I can read Swagger.
