Documenting an API is important.
When it's publicly available, this needs no additional explanation,
but even if it's not publicly available,
your API should 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,
like how do I integrate with this API over and over again because 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 can result 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 is that thing that allows documenting an API.
And that is indeed one of the use cases for it.
Let's see what drives this.
What you're looking at at the moment is part of an
OpenAPI Specification in JSON.
In fact,
you're looking at the specification we are going to
work with throughout the course.
What this in essence is is a standardized description of your web API,
either in JSON or YAML format.
It describes the capabilities of your API and how to access it through HTTP.
If we have such a description of our API,
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 is 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.
And then we need another component that does something with that specification,
for example a component that generates that documentation UI from it.
But from an OpenAPI Specification, other things can be generated as well,
like client‑side DTO classes or even API tests.
So, OpenAPI is broader than just something that is used for the
documentation UI. You can find the full specification format via
the link on screen, but you don't have to. We will dive into the
details during the course.
The current version of OpenAPI is version 3.0. An OpenAPI Specification is
often referred to as a Swagger Specification as well.
Both terms are interchangeable, but OpenAPI is the preferred term.
Once you start surfing around for information on OpenAPI or Swagger,
you will quickly encounter terms like Swagger UI,
Swashbuckle, NSwag, and so on.
So, let's clear up the confusion and define what all of these are and how they are related to each other.