-: Okay, so now, let's see a demo of OpenAPI.
And in this lecture we will see two demos.
The first one is this, The Swagger Pet Store.
Pet Store is a fictional pet store, obviously,
created by Swagger to demonstrate how the Swagger
documentation looks like.
So let's click this link, and this is how it's look like.
Now this is a typical open API documentation
and what you see here is of course
the title, the version, some general information.
And the really interesting part is this one.
Here you see a list of APIs or endpoints that you can use.
Now note that for every endpoint,
you see the verb, POST, PUT, get,
here is a DELETE.
All of them are grouped under PET
with some short description.
And if you will click this action
then we'll get a full documentation
about this specific endpoint.
So we see here a description, we see an example
of how it looks like, and we also get a list
of the responses expected from this action.
Now let's go to this action.
This action, as we can see, it finds PETS by status.
This is a GET action and let's open it.
And as we can see in the parameters section
there is a list of what are the parameters we can use.
Remember that we are looking for a pet
by status and the statuses are available, pending or sold.
And what kind of responses can, can we expect?
So there is of course the 200,
which means that the operation was successful and 400,
which means there was some problem
with processing the request.
Now notice this button.
They try it out, so click it
and now we can execute the request.
How do we do that?
Let's pick some status from the list.
I'll pick the available and click execute.
Now see what happens.
So Swagger executed the endpoint and called it
this is what it called.
So this is a cool command and get
and this API with a parameter that we specified.
And also, since the response content type here
is application XML.
This is the header that was sent to the API saying
that the expected format is application XML.
This is the actual URL of the endpoint that was accessed.
And this is the response that we've got.
So you can see here a list
of pets that were returned by the server.
And as you can see, this is in an XML format.
Now let's go
to this dropdown list and pick application/JSON
as the format we would like to get from the server.
And click execute again.
And again the request was successful.
You see the response code here
and the response body now contains JSON format.
So you see that the format was set using this dropdown.
And as you can see here
the header that was sent to the server said
that we now want the response to be in JSON format.
Now the interesting part here is that not a single line
of code was written in order to create this test bed
this test client, it is generated automatically
using Swagger.
So this is how a typical Swagger documentation looks like.
So again, we have a list of actions with the verbs.
They are grouped by some kind of title
and provide a very convenient user interface
for reading the documentation and testing the API.
So this is a field demo and this is nice.
And let's go to the second one.
So the second one is called Swagger Inspector.
And what Swagger Inspector allows us to do is to
provide an an API
and Swagger will automatically
generate buildbot documentation for this API
just by inspecting the endpoints.
So we will use the Inspector to generate documentation
for the API we built in Beeceptor.
So click this link.
Great. And now let's go to Beeceptor
and copy
this full URL
and click mocking rules.
And let's memorize one of the API's here.
I'll go for this one.
API/v1/order.
Great.
So let's go to the Inspector
and paste the URL /API/v1/order
and click send.
Now what we've got here is something that looks really
similar to Postman.
So we have the URL, we have the response
and we have some data about the request.
But the more interesting part is right here.
Now what's happening here is
that the Swagger Inspector shows us what request we made
and we can convert this request to Swagger
or OpenAPI documentation.
Now, in order to do that
I'll mark the request that I want to convert
to the documentation and click the create API definition.
Now, if this is your first time visiting the Inspector site
then you will be asked to sign up.
So I'll skip this part.
I am already signed up.
So sign up to the Inspector
and then come back to the site and do it again.
And after you do it, click the create API definition
and the definition was created
and it is hosted in a website called SwaggerHub.
So let's go to SwaggerHub.
And now SwaggerHub asks us if we want to
define some basic information about this documentation.
So let's give it a name and we will call it demo-rest-api
and the version, let's say it's version one
and let's make it public and import OpenAPI.
So now we have this Swagger documentation ready
and we can even edit it.
So look here at the right hand side
of the screen so you can see a reflection
of how exactly the documentation will look like
for the developers using it.
So we have here a default title
which is not very informative.
So you can modify it right here in the documentation.
And let's change it to demo API for the REST API course.
And you can see that it'll change right here.
Let's also change the description.
This is a demo API created for the REST API course.
And again, we see it right here.
And here you can see the action
that we've created the documentation for.
And if we'll click it
we'll see exactly what we saw before at the pet store.
So we have the expected response code
we have an example of what is returned from the API
and everything looks just the same.
So this was a short demo
of how to use the Swagger website and the Swagger Inspector.
And now let's move on
and explore the format of the Swagger documentation.