API Series Part 2b - Add Non-Intrusive Markdown to Swagger UI

In the last post we added a short description of the API using markdown. The Description property of the Info class gets rendered at the top of the page above the list of actions.

In this post we are going to take that a bit further. One problem with putting documentation in your Swagger docs is that if you put a lot of detail there then you are forced to scroll down every time you view the Swagger UI of your API. This can get pretty annoying quick. So we'll look at a trick for adding as much detail as you want but avoiding the scrolling issue.

API Series Part 2 - Documentation - Swagger

Swagger acts as both machine and human readable documentation for your APIs but also via the Swagger UI offers you a way of interacting with your APIs easily. We are going to embed a Swagger UI in our APIs that will load when you press F5 making it hassle free to test your API during development and testing.

We are going to add Swashbuckle.AspNetCore to our ASP.NET Core 2.0 API to create this embedded Swagger UI.