There are certain things in life that you take for granted but didn’t know you did until you didn’t have them anymore. Swagger is definitely one of them.
I remember coding back before 2000. I had my “.001” to “.###” numbering conventions for archiving various revisions of files as I wrote code so I’d have “checkpoints.” Then I was introduced to Perforce and SVN usage. That definitely made things easier, but it wasn’t until I started coding a side project without source control that I realized how much I needed SCM systems. Unit testing fell into the same category. I never had a problem just running a program and doing some simple automated testing or manual testing and then calling it done. Then I discovered JUnit, and the rest of the equivalents. That certainly made things easier, but it wasn’t until I had to pick up my first legacy code base to support that didn’t have it before I realized how much I needed a legitimate unit testing system. Swagger is definitely in that camp for REST services.
Before I discovered Swagger I used to just meander my way through code bases to discover what the call structures were supposed to look like. Yes ASP.NET automatically produced some nice documentation but I wasn’t going to code on .NET anymore. Then .NET core happened. I still wasn’t going to go back to ASP.NET though. I have fallen too much in love with self-contained web services systems to go back to having to host things in IIS or some other platform (or settling for being second rate on some self hosted container). Then I found NancyFx and it hit all the points I was looking for except one; it didn’t do Swagger under .NET Core 1.1 well and the Swagger for Nancy seemed to be driven by a whole separate module rather than in-line annotations.
That’d be okay, I assumed, I’ll just go back to meandering through the code for my code examples. How wrong I was about that. At this point I need something like Swagger. Sure I can muddle my way through, or provide some code samples or cURL examples but why? That’s what Swagger does for me. As my frustration levels built through that project I powered through all the while thinking, “God I hope they do annotations for Swagger for NancyFx.” In fact they are doing just that.
Here is the link to the documentation for their alpha implementation of using annotations inline. It’s got lots of rough edges, hell it’s an alpha, but I can’t wait for this to hit it’s release status. It is exactly what I’m looking for.