Previously I've built PowerShell based processes to bring in the user timeline feeds and push to Office 365/SharePoint Online solutions. However I now need to create a more advanced integration using c# and .Net Core.

Looking at the Twitter API reference it's huge. So I wondered if it supported Swagger or RAML as you can code gen off those helpful little API Documentations. Turn's out there was a RAML for Twitter on the MuleSoft AnyPoint site:

https://anypoint.mulesoft.com/apiplatform/popular/#/portals/organizations/52560d3f-c37a-409d-9887-79e0a9a9ecff/apis/6308/versions/6302/pages/31760

It seems MuleSoft also have built some generators such as a CLI and a Visual Studio Extension to create API Clients and Servers from RAML. Unfortunately at this time, a bug in the generator gave me an exception which went a little something like:

Unable to cast object of type 'System.Object[]' to type System.Collections.Generic.IDictionary`2[System.String,System.Object]'

It's probably fixed by the time anyone reads this, but not being phased I decided to convert to Swagger and generate from there.

Converting RAML to Swagger

I've used APIMatic's very cool transformer on other projects, so was perfect for this scenario too.

I entered the RAML Url into the converter and clicked the inviting "Convert now" button with eager anticipation.

Love the very Apple Mac-ish console output showing you the results:

From there I received a root-Swagger20.json file download, thanks APIMatic!
Next up, create a C# client.

Generating C# from Swagger

Ok, so I converted my RAML to Swagger, and now I need to generate some C#.
I installed NSwagStudio with some chocolately goodness, a cool package manager for Windows.

It took me all of about a minute to generate my Twitter.cs API Client.

  1. Add the path to your Swagger file in the Swagger Specification Url field.
  2. Specify your Output file path, making sure to actually specify a filename, not just a directory.
  3. Click "Generate Files"

Sweet, now I have my Twitter.cs file. Opening it with VS Code gave me a quick look at the very extensive client that's been auto gen'd for me:

Hopefully this is helpful to show how working with API's can be much more efficient when the good dev's add a documentation system like Swagger or RAML. It also relies on good companies and individual's providing useful tools such as the code generators.

If you are building your own API using the .Net MVC WebAPI framework, I highly recommend checking out Swashbuckle. It's easy to hook up and auto gen's your swagger for you dynamically. You can add attributes to fine tune the output, provide examples and add more information.