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's 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 may result in three or
four API S doing mainly the same thing.
And thus a lot of money is wasted on developing and
maintaining them through swagger or open API.
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 is in fact the de facto standard these days.
And I'm assuming that that is 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
open API specification in Jason.
In fact, it's the specification generated for our API.
In essence,
this is a standardized description of your API either in Jason or Ja ML 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 to do something with it.
The most common example being generating a documentation you I from it.
So that's the story.
We have a description of specification and from that specification,
a documentation U I 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 is our first
requirement and then we need another component that does
something with that generated specification,
for example,
generate that documentation U I from it that can also be used to
test our API that's our second requirement.
We'll get to how we can meet these requirements immediately.
But first,
let me clear up some potential terminology confusion
because over the years terms like swagger,
open API, swagger U I and so on have not always been used correctly.
An OPEN API specification is often referred to as a
swagger specification as well.
Both terms are interchangeable but open API is the preferred
term swagger then is sort of an umbrella term,
it's a set of open source tools built around that open API specification.
These are tools that help with creating an open API specification.
For example,
swagger editor that help with rendering A U I from an open API specification.
An example of that is swagger U I or tools that help with generating a
specification or client libraries from that specification.
All right, back to our two requirements.
We need some kind of tool or component that helps
working with open API in a SP .NET Core.
That is where Swash Buckle dot A sp .NET Core comes in.
This piece of middleware has two main responsibilities.
First,
it generates an open API spec for our API that matches our first requirement.
Secondly, it acts as a wrapper around swagger.
Ui it provides an embedded version of it which is driven by
the generated open API specification and that is a match
with our second requirement.
So if we add Swash Buckle dot A SP .NET co to our API
project and configure it correctly, we get both of these.
Let's have a look at a demo for that.