-: Starting this up, let's focus
on the documentation of your REST API.
Your REST API consumers need to understand your REST API.
They need to know what are the different resources
that are being exposed?
What are the different actions that can be performed?
And they would also need to understand
the request and response structure.
They need to understand what is the format of your request?
What is the kind of response they can expect back?
And do you have any constraints or validations?
So your REST API consumers need to have
a really good understanding of your REST API
so that they can play with it.
Well now we talk about REST API Documentation.
There are number of challenges.
How can you ensure that your documentation
is up to date and correct?
Accuracy is always a big challenge.
Your documentation might get out of sync from that off code.
Another important thing is consistency
of your documentation.
You might have hundreds of REST API in an enterprise.
How do you ensure that the documentation
for all these API is in a consistent format?
When we talk about REST API documentation
we have two options.
One is manually maintain documentation.
Basically you can have a document
or a HTML file where you maintain documentation
related to your REST API.
If you're manually maintaining the documentation
then you'd need to always put in the effort
to make sure that it is in sync with code.
The alternative is to generate the documentation from code.
Earlier we wrote the code for our user resource.
Can we use this code to generate documentation
for the user resource?
So that's option two, generating documentation
based on your code.
In this step, let's explore option two,
generating documentation for your REST API from code.
There are two very important terms that you need
to understand whenever we talk about REST API documentation.
This is in respect you of the language
you are making use of to develop your REST API.
Whether you're billing your REST API using Java,
Python, Node.js or any of the languages.
These two terminology are pretty common.
Number one is Swagger.
Number two is Open API.
Let's take a quick peek into history to understand
Swagger and Open API.
In 2011 was when Swagger Specification
and Swagger Tools were introduced.
Around this timeframe, we started to build a lot of REST API
and we needed a format in which
we can document our REST API.
That's where Swagger came in and it provided a specification
called Swagger Specification.
And Swagger also provided a number of tools
to visualize this specification to make use
of this specification.
Swagger became really, really popular.
It almost became the defacto standard
for documenting your REST API.
And in 2016, Open APIs Specification was created
based on the Swagger Specification.
A number of large enterprises came in and there
was an open standard called Open API Specification
which was created as a standard for
documenting your REST API.
This was based on this Swagger Specification.
However, a very, very important thing to remember is
that these Swagger Tools continue to exist.
So the Swagger Specification became Open API Specification.
However, Swagger Tools, those are basically
the tools to visualize and consume your REST API.
They continue to exist.
For example, Swagger UI.
So Open API Specification, earlier
this was called Swagger Specification.
This is nothing but a standard language agnostic interface
to define your REST API.
You can see an example of the Open API Specification
in the left hand side image.
This specific example is using Open API 3.0.1 version.
As part of your Open API Specification
you can define where your specific REST API is exposed.
What are the different resources that are being exposed?
What are the actions that you can perform
on your, on your REST API?
So your Open API Specification helps you to discover
and understand REST API.
This was earlier called Swagger Specification.
And Swagger UI helps you to visualize
and interact with your REST API.
Having this documentation is good.
However, you'd want to have a tool which will
enable you to interact with the REST API;
look at it in a more visually pleasing way.
That's what Swagger UI provides you with.
It provides a great UI around the Open API Specification
and it also enables you to easily play with your REST API.
In this step we got a quick introduction to some
of the important things that you need to know
about REST API documentation.
We talked about open API and we also
talked about Swagger UI.
In the next step let's generate documentation
for our REST API.