What is Swagger | Swagger For Beginners | API documentation | How to use Swagger | Viswateja

hello everyone in this video we'll try to understand what is Swagger and how can we use Swagger for documenting our rest apis so let's get started like how this particular video is divided like first as I said we'll try to understand what is figure why we need sugar and we'll see how can we run as figure in a container and then a build a simple python flash rest API deploy in a container and write a Swagger file for that particular rest API which we are building using swagger editor and how can we connect those Swagger files to the Swagger UI to understand uh you know the our rest apis in a better way right so to start with first what is figure so Swagger is a built on open API specification it's like a blueprint for your rest apis so it tells you what API does how to use it and what to expect in written so this make it easy for developers to understand how to use the API and it also make is easier for the other developers to create tools that work with other apis so it it says in in a very short Swagger is used to document your rest apis or typically any apis so let's just try to understand what I mean by you know uh documentation let's say I'm building a simple application like a calculator application let's not make thing complex I am building a calculate replication so I have an addition subtraction difficult multiplication what not I have some couple of apis now I am building it and obviously maybe it need to be consumed from a web application or maybe some other extreme may use it in in any other form any other form so obviously I need to provide them the documentation right so how about this maybe if I can make it in a better way maybe like this it's cool right so you have a rich UI it says you know this is about the calculator application not just that you just expand this okay what it does is it does addition it says like We'll add two values did you see this this is a sample request not just that you click on try it out and yes you can test your rest API here itself let me click on execute did you see I got a response 3 plus 2 equal to 5 that's so cool right now from this to this makes lots of sense for the developers who wants to consume uh use the rest apis right that's so cool right and yes that's what we are going to cover Now by now you might have understand what are the benefits of s figure right it makes it easier to understand how API works as we just seen here right uh like you know what is the the URI of this right and what is the sample request if you trigger it what is the sample response you get right there's so many features which we are going to discuss right and it can help improve the documentation of APs of course it's this is this is far far far better than the traditional way of documenting right and it can also use to generate a code that consumes or produce data from API we'll also see that what what it mean by it right it can help automate the testing of apis we'll also see that how it can help right and where to use by now you must have understand when to use figure right a like we might use figure to document uh if the if I have a public apis and I want to make it public as I said right that anyone can make use of it so with this yes it's simple to use right and as a team you know like I am building some apis where some other team members want to consume it instead of this I'll give them this it will be easier right for them to understand so yeah the couple of real-time use case just support my previous statement like let's say for example you're building a microbe Services right let's say item API is one of the service very internally I have four to five different micro Services right so now I can effectively document it and I can share this links to whoever whoever wants to consume those apis so as I said like uh you know uh I'm building a complex web application uh where I have hundreds of micro Services right like say for example I'm building a e-commerce website this is a couple of right like items like you know get items adding deleting updating what not like you want to know about the price payment there's so hundreds of apis right let's say for example when you talk about uh the particular module called uh relate I mean item API right so here you know I have four to five different micro services so now using swagger it will be very easy for the end user when I say end user who is going to consume your apis easy for them to understand decode your APS instead of they bug you you know every time you know what is the sample request I gone through this documentation can you tell me how can I test it now here done right so that's the best way of swagger so as I said we'll take a simple example uh maybe yes as I said a simple calculator application right so it it is I'm using a flask as usual so we also obviously need to use cores you'll I'll tell you why we need to use cars in some time right if you see what it does is it's doing addition subtraction multiplication division and there is one more guy what this guy does looks like it is reading some file and sending a response right now this is what the file that we are going to Target now now yes I think yeah as I just shown uh yeah how did I come to this screen right obviously and for that I need to write some file and that we call it Swagger file and yeah do you think I'm definitely not comfortable with writing this complicated Json file so many flower brackets definitely not but yes Swagger has a beautiful tool called Swagger editor so if you see here uh I just paste this here did you see we got it that's so nice right in case I got one more API just you you know copy this sample just say enter and say paste uh yeah of course there's a duplication so in sub uh say add I'll just say addition you can see it here right so there is a and b here I'll say d and e did you see that was so quick right now hope you understand we will just try to decode uh this structure what exactly is path Services info will decode everything don't worry about that but first we'll see how can you know will connect so when I say connect this particular Swagger file with our Swagger UI so that we can see it right so as I said right so let's say if you see this is a a calculator replication right so where it has a different micro services like one of the micro Services addition the other one is subtraction right now as I just shown you using swagger editor how easy to edit your rest API documentation right so now I want to deploy this obviously the best way is like a containers right I have a Docker file in case in case if you guys are not familiar about what is Docker how to use Docker I already made a video I'll keep that link in the description please watch that so yes this is a simple Docker file and this is my flask rest API and this is a Swagger and this is the requirement.txt file uh whenever you run your containers I mean whenever you build your image so all this will be packed right and create as an image so I'm using a podman here uh like this is one of the alternative tool for your Docker desktop so yes so if you see my container is already running here and this is the container for uh what you call for it was Swagger UI so whatever you see here that's is actually deployed in this particular container right how to come to this it's very very simple you just need to install a Docker or a podman in my case I'm using podman I started liking it so yeah so in case if you are using Docker you have to install it first obviously run this command once it pulls the image and run this particular command that's it your Swagger UI is will be up and running right in case if you want to try podman like me instead of Docker you just say pod man that's it so rest everything behind the screens the same magic right so now yeah that's how you know you can oh I'm sorry that's how you can run your Swagger from your container right so whenever you open the segger UI the first thing you see is a pet store this is a sample example from the swagget team right we'll discuss this now I need to connect to my Swagger document right that's what the point of discussion now right so now as yes as you see I said one strange guy here right and this guys read this figure file and give me as a Json structure right and if you see I'm also including that speaker file as part of my container right so let me run this localhost I think it's five triple one did you see cool right now let me copy this URL and paste it here and just say enter that's it so now your Swagger UI connected to uh your calculator application right similarly let's say I have uh what you call some other application uh maybe something relative stats stat statistics just for the sake of example I already have it let me run this I'll say s t a t s and as I said don't worry about this watch my video it'll be very clear so similarly I have one more container running where I have the basic statistics file a related logic so it runs on Port okay I give it another way I'm sorry let me delete this and rerun oh where are you guys where is stats yes s t a t s and host Port is 5002 the container Port is triple nine and here if I say 2 oh sorry yes we got the other one copy this URL paste it here that's it did you see so like it's given average you can just click on try it out and you say two average you know right two plus two divided by 2 is equal to 2. am I right yes oh yeah there's something wrong uh with the response but you guys understand the concept right it says some course error it's because yes I said we are going to discuss about this right let me open this stats uh python code uh give me a minute please where is it stats yes oh it has cars enabled the strange but why is it coming like this we'll try for a mode just try it out execute just check in the containers if we are getting any errors there's no error I will just try for the I think we already tried for addition right try it out execute yes we got a response subtraction 1 minus two minus 1 that makes sense let's not try to debug but the intention of this video is to make sure you understand you know uh the benefits of spaga right but again as I said right so in a given project let's say for example you take an example of e-commerce itself right there are so many modules like this you know get API price payments what I just shown is three as I said there will be so many right and for item API as I said I have four apis Here and Now for these four apis I'll have a separate documentation and this for the four apis I'll have a separate documentation so like for each documentation we'll have one URL as you shown here if you see 5002 is stats if I say five zero zero one it's like a calculator application you can see here right so similarly for each each module you can have a separate Swagger file or for all the modules you can have a singer Swagger file it's up to you like uh it's totally depend on Project to project but I personally prefer to have a separate Swagger file for each module right so there are some Advanced configurations right like where you can create a drop down here right insta files instead of locals host 5002 you can say stats right for five double zero one you can see calculator right there are some configuration that can be achieved right but ultimate goal is uh hope you understand the benefits of you know uh using swagger right and yes I before we close this I would like to explain you what are the you know the different component that is Swagger file has right so this is the as I said this is a pet store a sample uh Swagger file that provides by this figure itself right so let me see what are the couple of components we have in the Swagger file like let me minimize all this cool stuffs right now start with info this is a very basic like it says like what this particular module does a brief introduction about this particular module right and then we have external documents in case if you have any external documentation you can refer this and then you have servers so this is very important so um to make it more clear let me yes did you see servers here maybe I'll copy this no no not required here you can see right so if you see like I have a Dev I have a prod like that you know you can configure right for Dev it's five double zero one for example and for prod it's five double zero three it's about you know you can mention you know uh three different environments you have and the three different respective urls uh to do it right let's say for example now it behind the screens it hits five double zero one let's say if I'm just changed to 5003 I'm not sure what happened something wrong but it usually select five double zero three and hits you know uh five double zero three right but ideally I'm not sure why it is not getting selected but yes ah you understand it right that's what the servers refers to right here in that case you know you have only one that's why in the drop down you see only one right and then tax this tags are pretty cool ah if you remember I told right like I can write a single Swagger file for all these three modules or I can write one second file for each of this module for item API one Swagger if a price one Swagger payment one second file right so in case if I am writing a single Swagger file for all these modules how can I differentiate it and that's where the tax comes in place so here I can say item API price API and what is the other one yeah the payment API right and this is a path this is the the major part right did you see I said pet when I say pet this is what your typical URI like for example for addition I'll say add and this is the ad which we are referring to here in this case it is better right and what is this this is actually your uh rest method for this pet right is is actually deployed this pet resource is using a put method right and as I said when I say tax it's false under pet right did you see here how many tags we have pet store user right you can see it here this is pet under the pet we have relevant apis and at the store we have relevant under the user we have relevant apis right so you can consider pet as one module store as another module uses another module right so that's how you can refer let's say if I say this pet I change this tag as an user did you see the pet comes under user right when I say it is a pet itself it came out and went under the bed now you understand the power of tax right so here you can I'm sorry the brief about what is the summary right and what is the description and this operation it is a unique ID it's not mandatory and then we are talking about your request body all right and you can give the description for your request body as well right you have two descriptions here one on a very high level another the description to your request body when I say request body your request structure that your API is expecting and what kind of content it expects it is expecting a Json it can also expect an XML right and this is a request body right similarly you will also have a response right so you can Define this 200 is a status code what is the description right again in the response you can get an XML or you can get an Json you can also you know uh Define an error course like 400 500 what not right so this is how in a given rest API a request body and the response body you can Define there is some beautiful thing that you can see here schema right we will discuss that did you see I'm sorry this is a sample request that this particular rest API expects where did I Define this and that's why there is another beautiful thing called components under schemas I defined it right and if you see this particular path under components under schemas it is referring to pet right component schemas pet under components under schemas right it is referring to what but we'll see that did you see it is referring to pet did you see it says required so it is saying the name and photo URLs which is this name and this photo URL are mandatory as part of your request right and then we are defining a property when I say property ID is one of the uh the request that it is expecting right and the type is integer the format is this and I am giving a sample data here that's so cool right now you understand from where this value is getting is coming from right it is coming from your components similarly you see name it is string and I said doggy that's an example maybe I'll say doggy right you can see it is like reflecting I just wanted to show you know this values are coming from here and you have a category and the category is again a dictionary it is referring to some other component that is so nice so that you know this category can be reused right and you see there is a category here now again as usual what is the type is object you are defining the property for this ID uh like the metadata for name the type is string example is you know dog now we also have a concept called reusability now this category can be used by some other you know for example APA as well for example tags right did you see stack it is also referring to another component schema and you can also see the schema structure here so of course right obviously as a developer I won't prefer to see this right my intention is to explain you how the Sega Swagger file looks like right you can click on the schema here and you can see it did you see for the name and photo URLs it says mandatory right because when I'm defining this scheme I said under the required I said name and photos urls are monetary that's why it says star so how convenient it is for the developer now right that's so nice right so yeah hope you understand the Swagger file and it's the different components the other point which I wanted to cover is this one it can be used to generate the code in my opinion that it it doesn't help much right but I just wanted to show you that there is such kind of option so you can say generate client where is python you click on the python it will generate a python code that actually calls this rest apis I can quickly show you that let me pull this here downloads yes come on man yes um yeah did you see you have test pad test tag it generates the documentation to it right but as I said I don't feel this is that much helpful uh did you see it also created a class that refers to your tag but at certain point it helps in case if you want to strictly Define your schema structure as part of your python code it it helps so because in case if you want to define the similar schema structure as part of your python so instead of you rewrite this this is so cool right so this actually helps me for example if I want to send a tax right with this with the help of this Lino I can Define the structure right but again it's a person to person but I personally feel it is it is doesn't make sense right so I think this is what I wanted to cover as part of this video hope you enjoyed so I had a good learning on speaker so we'll see you in the next exciting video thank you

Channel: TejaWithData

Views: 2,388

Keywords: Data Science, DataScience, python, viswateja, swagger, flask

Id: xQfMARPNycI

Length: 27min 34sec (1654 seconds)

Published: Sun Aug 06 2023