Instructor: So let's go back to the Petstore,
and if you look closely at the documentation page,
you can see here a link.
Now, this link ends with swagger.json.
So, swagger.json is the name
of the documentation file generated either
by Swagger itself or by the Swagger library used
for the specific platform you are using.
So, we want to look closely at this file.
So, let's download it to our computer,
right click and save link as,
and let's save it in our downloads folder and click it.
So, in my PC, JSON files are opened in VS Code.
You may be using some other tools,
but it doesn't really matter.
What we want to do is to explore this file,
and understand what, exactly, it contains.
Now, it might seem a very long and complex file,
but as you will see in a minute,
it's actually quite simple and basic file,
and very, very easy to understand.
So, let's start, go over it.
First we have the Info field,
which contains some general information about the API.
So, we have a description, this is a sample server,
petstore, petstore server, et cetera, et cetera.
We have the title, we have the version,
we have the terms of service,
some contact email and the license.
And if you will go to the documentation page
on the Swagger website, then you can see
that this data is exactly what is displayed right here.
This is the title, this is the version.
This is the descriptions that we saw.
Here is a link to the terms of services,
and the license, and the contact.
So, everything is reflected quite easily
in the documentation website itself.
So, let's go back to the file, too,
and let's skip here a little bit
and go to the path found in the file.
So, each entry in the passage contains a single endpoint
and the first endpoint we see here
is a pet endpoint with a POST verb.
Now, what we see about this endpoint is, first, its tag.
So, the tag here is pet,
and now let's skip back to the documentation website,
and you can see here that this is the endpoint.
As you remember, it is called pet with the POST verb,
and remember that the tag that we have, a tag named pet,
the tag is used here to group the various endpoints
into specific titles.
So, the pet here, is the pet here.
So, we know that this endpoint is under the pet tag.
Okay, so let's continue reading this file.
So, as a summary, we see that this endpoint is used
to add a new pet to the store,
and that it consumes and produces either JSON or XML,
and that there is a single parameter
in the body of the request,
and this is a description of it,
and for the response we can expect a 405,
meaning Invalid Input.
So, to summarize, this is, this part,
is a documentation of a single endpoint in the API.
So, now let's go and see
how all this data is reflected in the documentation page.
So, as we said earlier, we can see here,
the description specified in the documentation.
Remember that the API gets and returns either JSON or XML.
So, you can see it here, JSON or XML,
and here for the response
and this is the response code that can be expected
when calling this API.
Remember that we saw that a response code of 405
can be expected.
So, this is basically the basic structure
of a Swagger JSON file,
and using this file,
you can generate a very professional looking
documentation that will attract many developers.
Now, the good news are that you don't really need
to write this file by hand even though it's really simple.
As we will see in the next lecture,
there are many libraries that generate
this Swagger JSON file for you from the API
and saves you the need to write this file.