What is Swagger, Swashbuckle and Swashbuckle UI

Question

This is my understanding:

• Swagger is a notation/rules to write documentation. But why is it called a framework (like Angular/MVC)?
• Swashbuckle is a program (JavaScript?) that generates the documentation (based on Swagger rules).
• Swagger UI displays the documentation. It uses Swashbuckle to do this.

Is this information correct? If not can someone explain in simple terms what Swagger, Swashbuckle, and Swashbuckle UI mean?

Also, what do I lose as an API developer if I do not use this?

Answer 1

Swagger is a notation/rules to write documentation. But why is it called a framework(Like angular/MVC)?

It is probably called a "framework" because its' purpose is to offer a systematic way of notating the interface of any RESTful service under the OpenAPI Specification. This is a big deal to developers because the spec is overseen by the Open API Initiative under the reputable Linux Foundation.

Swashbuckle is a program(javascript ?) that generates the documentation(based on Swagger rules)

Swashbuckle is more of a package (or a library) that you can make use of in your .NET Web API projects. It's purpose, as you have correctly indicated, is to generate the Swagger spec for your project. Additionally, the Swagger UI is contained within Swashbuckle so if you are developing an API in .NET it's really a nice one-stop shop of a package. It is almost entirely written in C#, not JavaScript.

Swagger UI displays the documentation. It uses Swashbuckle to do this.

Yes, it does display the Swagger spec in a nice, human-friendly manner. However, Swashbuckle is not a necessary component for this. They are, aside from what I just said previously, completely mutually-exclusive.

Also what do I lose as an API developer, if I do not use this.

This is now entering into the realm of opinion but I'll try to be objective about it. I use Swashbuckle to assist in the creation of clients for my application APIs. After getting past the implementation learning curve (which wasn't much), this package has saved me quite a bit of time of writing the clients myself. Writing a web client is a trivial thing for small applications but enterprise-level applications have a tendency to keep growing and/or changing in complexity so it is nice to have the creation/updating of these clients completely automated.

In short, if you decide not to use it you must either resort on an alternative method of API client generation or write/update the clients yourself. If you are only developing the back end this may be completely pointless to you but it would certainly help whoever is responsible for creating the client apps that will consume your API services.

I hope these answers have been helpful. Cheers!