Umbraco APIs with Swagger

Usually, my Umbraco projects involve extending Umbraco to contain custom APIs. As with any API we write, developers want to document it, for other devs, or maybe just ourselves!

 

Swagger UI lets you easily document your REST APIs and allows you and other developers to test with it. Here is a quick tutorial on including Swagger in your Umbraco project.

First of all, let’s get a fresh Umbraco site, install umbraco as per instructions here and follow the install wizard: https://our.umbraco.com/documentation/Getting-Started/Setup/Install/install-umbraco-with-nuget

Next up, you will want to create your own APIs, Umbraco docs have details on how to create your API endpoints.

I have made a sample one for this prototype, a custom content api that can give Umbraco content via API, it is on /umbraco/api/customcontent/getname

The .Net package to implement Swagger UI is Swashbuckle, Install via NuGet on your Umbraco project and rebuild the solution.

If you now go to /swagger you should see your API docs.

At this point I got an error:

"Not supported by Swagger 2.0: Multiple operations with path 'umbraco/backoffice/UmbracoApi/Content/GetEmpty/{id}' and method 'GET'. See the config setting - \"ResolveConflictingActions\" for a potential workaround"

 

If you get this, open /App_Start/SwaggerConfig.cs, this file is added when you installed the nuget package and controls how Swagger works.

By default, this line will be commented, uncomment it:

c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());

Now rebuild and open the /swagger URL again and you should see your API docs! Although, you may notice your API is hidden in between all the API endpoints that make Umbraco work. This is probably not something we want to show with our own API docs, so let’s hide these and show only our own custom API.

To do this, we need to create a document filter. These let us only show APIs that match a set filter in our Swagger docs, so we can control what endpoints people can see!

I have created an example that only shows endpoints that contain “customcontent” in the url, but you can customise this to whatever you want. I created the file UmbracoSwaggerFilter.cs, see example below:

 

Now you must go back to the SwaggerConfig.cs and tell our application to use this filter. Add this line (there should be an commented “c.DocumentFilter” line to guide you to where it should go):

c.DocumentFilter<UmbracoSwaggerFilter>();

Now, in the swagger docs, we just see our selected API:

Yay! Some nice, tidy API documentation!

Hopefully this is useful to you, or even just to future me :) As always, please say hello on Twitter if you have any feedback.