Documenting an API is important. For publicly
available APIs, this goes without saying,
but when an API is not publicly available,
it should also be documented.
Imagine you're building an API for your fellow developers or one
that will be used by other teams in the company.
There is of course the fact that you don't want to spend your time
answering the same question, how do I integrate with this API,
over and over again; time is money. But there's more, if the API
isn't correctly documented,
other teams in the company might not know what it does
and start developing it themselves.
In the end,
that results in three or four APIs doing mainly the same thing, and
thus, a lot of money is wasted on developing and maintaining them.
Through Swagger, or OpenAPI, you can solve this.
A lot of people have heard of Swagger or seen it in action and know that it's
that thing that allows documenting an API, amongst others.
It's, in fact, the de facto standard these days, and I'm assuming that's why
Microsoft chose to include it in its default templates.
Let's see what drives this.
What you're looking at at the moment is part of an
OpenAPI specification in JSON. In fact,
it's a specification generated for our API. In essence,
this is a standardized description of your API,
either in JSON or YAML format. It describes the capabilities of your API and how
to access it through HTTP. If we have something like that,
we can have tools and components that use that description or
specification to do something with it, the most common example
being generating a documentation UI from it.
So that's the story.
We have a specification, and from that specification,
a documentation UI, like a web app, can be generated. But unless we want to
manually write such a specification, we need some kind of component or tool
that generates that specification by inspecting our API. That's our first
requirement. And then we need another component that does something with
that specification, for example, generate that documentation user interface
from it that can also be used to test our API. So that's our second
requirement.
We'll get to how we can meet these requirements immediately, but
first let's clear up some potential terminology confusion, because
over the years terms like Swagger,
OpenAPI, and Swagger UI have not always been used correctly.
An OpenAPI specification is often referred to as a
Swagger specification as well.
Both terms are interchangeable, but OpenAPI is the preferred
term. Swagger, then, is sort of an umbrella term.
It's a set of open‑source tools built around that OpenAPI specification.
These are tools that help with creating an OpenAPI specification, like
Swagger Editor; tools that help it rendering a UI from an OpenAPI
specification, an example of that is Swagger UI; or even tools that help it
generating client libraries from that specification.
Alright,
back to those two requirements. We need some kind of tool or
component that helps with working with OpenAPI in ASP.NET Core.
That's where Swashbuckle.AspNetCore comes in.
This piece of middleware has two main responsibilities.
First,
it generates an OpenAPI specification for our API. That
matches our first requirement. And secondly,
it acts as a wrapper around Swagger UI.
It provides an embedded version of it,
which is driven by the generated OpenAPI specification,
and that is a match with our second requirement.
So if we add Swashbuckle.AspNetCore to our API project, we get both of these. Let's have a look at a demo for that.