How to document api rest
Swagger API documentation tutorial for beginners - 1 - Intro to API documentation with Swagger
Timecodes:
hello everyone my name is Dave Butler in
this tutorial I'll be taking you on a
journey to documenting your API and I'll
just show you what this looks like we're
going to be using one of the best tools
for documenting API is called swagger
it makes documenting your API very easy
and neat and it also helps people to
test out your API so the developers
checking out your API can actually test
it on the documentation itself and be
sure it's working
not exactly what to expect before
implementing it so here is swagger two
to visit this site adjust with it pet
store that's what a lot I owe pesto the
swagger that IO is a sample API
documentation all the information is
just dummy information but they put it
up just to let you know how swagger
works so this is the default interface
and it was built with HTML and
JavaScript so if you already know some
HTML and JavaScript you can download
this interface and them edited which
we'll be doing
further down the tutorial and I can edit
it to match your website's theme or
color and this is it
you have swagger pet store you basically
exercise your right to code from a file
and that file will be a yellow file in a
file that has them low Tiamo I'll show
you shortly
but yeah Mon like this when you tell you
that when you write the code that will
display this this web page now look at
what it looks like you have a
description of your API and very
important links that the user will read
and then you also have your schemes
which could be HTTP or HTTPS or both
that is if your API your website is HTTP
or HTTPS you specify it in the file then
you also have your endpoints desire
resources you have a pet resource then
you have several endpoints inside page
so if I minimize this you'll see that
there is a pet resource as a story
source and
the story sauce there are four endpoint
CF get post get delete that is at these
different end points for each one I can
click on it and see for that details so
but before then let us look at some
other end points you have user end point
users a resource with the description
and several end points and that is how
powerful this is then at the bottom you
have models I will show you how the
models let us look at one end point v so
which is a random endpoint that creates
a user later see the one that gets an
odd ID find purchase order by ID so
let's just get this one take this one
and if you look at your right hand
you'll see that we can try it out but
before check out the try out button
we'll see that it has the different
parameters the description of the
parameters that we're going to send one
is the order ID so when we understand
this endpoint we are going to see this
order ID now this endpoint every
endpoint day is going to be preceded by
this curl the developer knows that hey I
have to add a store dot swag and of Iowa
and it has to be easy to be so I'll add
HTTP slash
pistol does one go to arrows like v2 and
I will now add slash store slash order
slash order ID in the endpoint all the
same so you're not describing that the
order ID must be an integer and there is
no description here for the guy and you
are specifying that this the content
type that will be returned when they
make a request will be XML and also they
can choose to get jason you understand
so you're the one that specifies the
secure system only outputs jason like
the one with it designed in this
tutorial the tutorial here it are only
output station then we have to specify
only jason now if at this point if not
if you don't know how to build a
is first then you have to visit my
channel my channel is youtube.com / c /
brain time or RG and when it opens you
click on playlists and you're looking
for this one API tutorial for beginners
step by step from scratch so when you
find this is like that getting videos at
this point in time you got to teach you
how to peel API loot using a very
powerful tool called laravel lumen after
building it then you can actually move
to document in your API so imagine that
if you've got to this point and you're
watching this video you've already
written your API or are just out of
curiosity you want to see what API
documentation is so in that code you
specify this location the yellow then
are a successful operation you will
specify the responses so 200 means a
successful operation from hundred means
invalid IDs applied for for order not
found you can specify as many as you
want to as few as you want but 200 is
always dead by default then you have
your example value which comes from a
model so if you click on the model will
see the model of the order ID you you
are the one that created this model for
order at the bottom so people can call
go to the bottom see your model which is
order and in the types the data types
that is expected you understand so they
can also see directly from the endpoints
in the click on this model they will see
this this is a very detailed API
documentation and you know the most
powerful thing about this tool is that
we can actually test it so let's say
your developer wants to the developer
wants to test this particular endpoints
or they can do is click on try it out
and it's going to take them to we're
going to enter the order ID you
understand your system only accepts
order ID so let's enter the variety so
we are just going to say just get a
random order
and hold ITEX exist in the pesto
database and this is a bottle to execute
remember you can always use your CSS
skills to change this page to suit the
general color scheme of your website so
when you hit on it it returns something
so this occasion has finished and we
chose Jason then it is telling us what
it send it actually sends this call
request and this the header and this is
the response that we got so we got the
order with the idea of 25 depend ID of
71 to 225 the order was created and was
shipped on 2,000 important and that the
start was operate available and is not
complete and here the response headers
that were received and here at the code
to successful you understand so any
ending body within your API
documentation and has this kind of
resource in the documentation they
really enjoy your API very very well now
let me show you how this is how you can
create this page just one simple way
then we'll go further down into the
tutorial to show other ways so you can
visit editor touch water look I owe and
when you open it you'll see that the
screen will divide into two where you'll
have your llamo which is like your
source code and your fourth end here so
this is the source code of this so let
me open it somewhere else all right an
open line Mozilla and up opened editor
that's working out IO
I just want to do to see the default
that opens up and the way this works is
that whatever you're working on if you
close the browser you close your browser
and open it any other time you will
still see that as saved what you're
working on and you can continue with it
so this editor helps you to generate
this page remember this page is familiar
that's what we just saw in our pet store
I
upon my other this is it in there they
are very similar so what the editor does
is just gives you the ability to write
the code while I'm watching it change
here so in some in the next tutorial
I'll teach you how to write this code
and have it ADT and then we can see how
to bring it offline because offline is
usually the best but I wanted to know
that this is llamo that is the Codex
cordial mode as you can see it doesn't
look like a most programming languages
but it's very easy to see and this lines
here kind of give you a guide looks like
Python or something so see in the next
tutorial where we'll actually start
working on this alright so we can
document your API and have your
programmers or whoever else is trying to
consume your APA to be able to use it
easily thank you very much seeing
subsequent tutorial don't forget to Like
and subscribe to my channel you see the
channel youtube.com slash c / brain 10
then pan to the right and hit on the
subscribe button more and more videos
are coming up by the a alright see you
next time
Related queries:
how to document rest api endpoints
how to document rest api using swagger
how to document rest api in confluence
how to document rest api with swagger
how to document rest api example
how to write rest api in java
how to write rest api
how to write rest api in python
how to write rest api in spring boot
