Detailed Notes
This video looks at one piece of our URL shortener solution. We have an API that we built and want to be able to provide documentation easily. We do this by embracing Swagger. This tutorial looks at some ways we can embrace documentation and make the API more useful to others through details and examples in our docs.
You can find out more through our online classes at https://school.develpreneur.com and register for free. Registration will add you to our email list and you will periodically receive coupons for courses as well as notifications of the latest releases.
Transcript Text
[Music] well hello and welcome back we are continuing our little short API shortener or URL shortener API application thing my Jake um I know I'm getting a little technical there but basically you give it a URL it gives you a short one back just like bitly or owly or any of those other ones what we're doing right now is in a we're going to wrap up talking about the Swagger uh API documentation piece because that's pretty darn useful uh just to catch you up as we have you know a nice document that has been created for us that we can you gets thrown out on a so somebody can take a look at our API and actually put it to use now a few extra things we have not talked about first one is there are Swagger things that you can do so if I just like get rid of these these which I've been using then what you're going to see right away you're going to see this page looks different when I first refresh it because boom it is not expanding it also if I do get uh try it out if I get hello then it's just going to say hey here it is here's response headers what I was using there we go is one that I'm going to expand the list and then I'm also going to have a request duration and an operation ID and these I got we talked a little bit of last time about chat GPT and how it can maybe help you out well that one I did how do I add extra content descriptions to flask uh rest X Swagger documentation and boom I do this and it gives me a bunch of nice little information things that we can look at so it's a quick way to be like oh hey how do I do this and we're gonna talk through that so this one now when we go back after we add just those couple now wh I got to restart the API that usually helps come here so now when I run it because I said automatically blow it out it's going to blow out all of the uh it gives you the full list here it also now when I run like get hello try it out execute so we didn't see before is I get a little request duration so I can see how long it took to run this thing which can sometimes be very useful so if I wanted to like uh get a shortened one try it out whoops and I do HTTP colon backb DP link dot us I think it's this way how did I write that yeah and give it like a I don't know 13 then it's going to come through and it gives me this and I can see here's my request duration so I get a couple extra things you can get to your um you your displays depending on how you want to do it it's a it's not a big deal necessarily however some things that are more would be each of these um is that we can do is we can come in and we can do and I believe it is below I want to make sure where the comments go yeah you can do and this is probably going to feel a little bit familiar you may have seen this before you can actually triple comment stuff so I can come in here and go one two three there we go and in here so I can say like see this even gives me like return uh string that API is up if it is and this is just to check if the API is up uh user will get an error otherwise there we go and let's do like the git so here we're going to say this is going to return the um uh Json packet of results and so if I do a git let me do it like this is if I do the G where's the G there's the git oh that's the wrong one uh this is the short and git I'm going to say this that has a resultant status oh that has data and Status such as the example below which I think did it already give me that somewhere um no it doesn't so good so I can put that there and say this is what it looks like wh let's do that there and this is uh takes a URL par URL equals of the HTML address HTTP Co DPL link. us quote And Then followed by an ID to R turn string a let's see a full URL okay and so let's just go with those two and what we will see now is we pull this in if we look at hello so here we can see that now I've got a comment sitting in here so uh that first line let's see hello where is that so this is just a check there you go it does that uh just just to check if the API is up user will get an error otherwise and notice it sort of rolls over and then uh return string that API is up if it is so we get something sort of useful there and down here forget so the same kind of thing takes a URL pram URL of the HTML htlm which we can actually clean this up a little bit um uh that's HTML so we're going to get let's say uh get the full URL from the shortened one and so now what we get um the user or they will get an error otherwise okay so now if we take this so now we can clean it up a little bit and it's going to look a little bit better because now what we've got here is get the full URL from the shorten one and then it says here's what it is return we can actually put you know a decent amount of information in there we can actually get a little bit more complicated as we want to uh up here this is the uh yeah if we remember we had the full description um and we had this we could actually do I think maybe let's see what happens if we do a triple here and instead do it like this and let's change our description actually let's do two uh let's see let's do this um let's say October 2023 let's do that and let's see how that looks so now we're going to look at the top and we're going to see there you go so it does it also gives us something similar here that we can get into it and and get fairly complex and have you know a nice set of document M ation uh these things obviously it's a little better to have your little uh you know sort of a a brief summary type title row and again with in doubt go chat GPT it up and then see what comes because you're going to see you know some pretty good information like here um I could come in here and I could actually look a little deeper into this one with additional metadata so I could do let's just do this so if I want to go into those settings a little bit more now I'm going to get something that's going to be a little more let's see um oh and I guess it gives me maybe that's the only ones we've got um there is some oh oh here we go so we can get some more information here we got title description contact and license we had title description um let's do this so let's go look at those real quick so title we had description we have contact let's do a uh let's do infomat preneur whop if I spell it right develop preneur docomo free to use let us how to improve it there we go so if we look at that then we're going to see something like this uh it doesn't oh it's not sh me a whole oh yeah so it doesn't really say that it's a license um nor does it say contact information which is interesting enough so it may be an old version of it or something along those lines um so we'll have to see maybe chat GPT doesn't know what the heck it's talking about uh that could be part of the case uh so if I do H I'm not going to go into it but you could you could do like this and then go expand three like and you could get some more information on maybe the additional pieces that you can add things like that so that will wrap this one up uh We've I think we've spent enough time now that you should have a good idea of how to jump into Swagger and document your stuff and it looks let's face it it's it's not hard it looks good it doesn't take you that long at all to add a little bit extra comments and stuff and then suddenly you've got something that looks instead of like we originally did that looks very hacky like this actually starts looking you know pretty like professional and stuff and you can have real information and have things like the the git where you can have like hey it's going to look something like this and there's additional things you can do within swager to like highlight those and and that kind of thing so that it makes it pop as a document goes that will wrap this one up uh we will come back next time and we'll just uh keep diving into things that we have learned that being said go out there and have yourself a great day thanks a lot for your time and we'll talk to you next [Music] time
Transcript Segments
[Music]
well hello and welcome back we are
continuing our little short API
shortener or URL shortener API
application thing my Jake um I know I'm
getting a little technical there but
basically you give it a URL it gives you
a short one back just like bitly or owly
or any of those other ones what we're
doing right now is in a we're going to
wrap up talking about the Swagger uh API
documentation piece because that's
pretty darn useful uh just to catch you
up as we have you know a nice document
that has been created for us that we can
you gets thrown out on a so somebody can
take a look at
our API and actually put it to use now a
few extra things we have not talked
about first one is there are Swagger
things that you can do so if I just like
get rid of these these which I've been
using then what you're going to see
right away you're going to see this page
looks different when I first refresh it
because boom it is not expanding it also
if I do
get uh try it out if I get hello then
it's just going to say hey here it is
here's response headers what I was
using there we go is one that I'm going
to expand the list and then I'm also
going to have a request duration and an
operation ID and these I got we talked a
little bit of last time about chat
GPT and how it can maybe help you out
well that one I did how do I add extra
content descriptions to flask uh rest X
Swagger documentation and boom I do this
and it gives me a bunch of nice little
information things that we can look at
so it's a quick way to be like oh hey
how do I do this and we're gonna talk
through that so this one now when we go
back after we add just those couple
now wh I got to restart the API that
usually helps come
here so now when I run it because I said
automatically blow it out it's going to
blow out all of the uh it gives you the
full list here it also now when I run
like get hello try it out execute so we
didn't see before is I get a little
request duration so I can see how long
it took to run this thing which can
sometimes be very useful so if I wanted
to like uh get a shortened
one try it out
whoops and I do HTTP colon backb DP link
dot
us I think it's this way how did I write
that yeah and give it like a I don't
know
13
then it's going to come through and it
gives me this and I can see here's my
request duration so I get a couple extra
things you can get to your um you your
displays depending on how you want to do
it it's a it's not a big deal
necessarily
however some things that are more would
be each of these um is that we can do is
we can come in and we can do and I
believe it is below I want to make sure
where the comments go
yeah you can do and this is probably
going to feel a little bit familiar you
may have seen this before you can
actually triple comment stuff so I can
come in here and go one two three there
we go and in here so I can say like see
this even gives me like return uh
string that API is up if it
is and this is just to check if the API
is
up uh user will get an error
otherwise there we
go and let's do like the
git so here we're going to say this is
going to
return the
um uh
Json packet of results and so if I do a
git let me do it like this is if I do
the G where's the G there's the git oh
that's the wrong one uh this is the
short and
git I'm going to say
this that has a resultant status oh that
has data and
Status such as the example below which I
think did it already give me that
somewhere
um no it doesn't so good so I can put
that there and say this is what it looks
like
wh let's do that there and this is
uh takes a URL
par URL
equals
of
the HTML
address HTTP
Co DPL link.
us quote And
Then
followed by an ID to R turn
string a let's see a full URL
okay and so let's just go with those
two and what we will see now
is we pull this in if we look at
hello so here we can see that now I've
got a comment sitting in here so uh that
first line let's see
hello where is that so this is just a
check there you go it does that uh just
just to check if the API is up user will
get an error otherwise and notice it
sort of rolls over and then uh return
string that API is up if it is so we get
something sort of useful
there and down
here
forget so the same kind of thing takes a
URL pram URL of the
HTML
htlm which we can actually clean this up
a little bit um
uh that's
HTML so we're going to get let's say uh
get the full
URL from the shortened
one and so now what we
get
um
the
user or they will get an error otherwise
okay so now if we take this so now we
can clean it up a little bit and it's
going to look a little bit better
because now what we've got here is get
the full URL from the shorten one and
then it says here's what it is return we
can actually put you know a decent
amount of information in there we can
actually get a little bit more
complicated as we want to uh up here
this is the uh yeah if we remember we
had the full
description um and we had this we could
actually do I
think maybe let's see what happens if we
do a triple
here and instead do it like
this and let's change our description
actually let's do
two uh let's see
let's do
this um let's say October
2023 let's do that and let's see how
that
looks so now we're going to look at the
top and we're going to see there you go
so it does it also gives us something
similar here that we can get into it and
and get fairly complex and have you know
a nice set of document M ation uh these
things obviously it's a little better to
have your little uh you know sort of a a
brief summary type title
row and again with in doubt go chat GPT
it up and then see what comes because
you're going to see you know some pretty
good information like here um I
could come in here and I could actually
look a little deeper into this one with
additional metadata so I could
do let's just do this so if I want to go
into those settings a little bit more
now I'm going to get something that's
going to be a little
more let's see um oh and I guess it
gives me maybe that's the only ones
we've got um there is some
oh oh here we go so we can get some more
information here we got title
description contact and license we had
title
description um let's do this so let's go
look at those real quick so title we
had description we have
contact let's do
a uh let's
do
infomat preneur whop if I spell it right
develop preneur
docomo free to
use let
us how
to improve it there we go so if we look
at
that then we're going to
see something like
this uh it doesn't oh it's not sh me a
whole oh yeah so it doesn't really say
that it's a
license um nor does it say contact
information which is interesting enough
so it may be an old version of it or
something along those lines
um so we'll have to see maybe chat GPT
doesn't know what the heck it's talking
about uh that could be part of the case
uh so if I do H I'm not going to go into
it but you could you could do like this
and then go expand three like and you
could get some more
information on maybe the additional
pieces that you can add things like that
so that will wrap this one up uh We've I
think we've spent enough time now that
you should have a good idea of how to
jump into Swagger and document your
stuff and it looks let's face it it's
it's not hard it looks good it doesn't
take you that long at all to add a
little bit extra comments and stuff and
then suddenly you've got something that
looks instead of like we originally did
that looks very hacky like this actually
starts looking you know pretty like
professional and stuff and you can have
real information and have things like
the the git where you can have like hey
it's going to look something like this
and there's additional things you can do
within swager to like highlight those
and and that kind of thing so that it
makes it pop as a document
goes that will wrap this one up uh we
will come back next time and we'll just
uh keep diving into things that we have
learned that being said go out there and
have yourself a great day thanks a lot
for your time and we'll talk to you next
[Music]
time