Openapi 3.0 / Swagger editor tutorial for beginners | Working demo | Simple explanation

tutorial by learn21 where we create uh courses for 21th century skill so in this video we'll look at swagger editor uh very sort of uh good functionality that this editor provides and this is for writing a documentation for the api and not only documentation you can give your customers if you have an api you can give your customers to try out these api also from here and see how the response will look right so the whole sort of interactive features also it has right and of course for anybody to integrate the api you can provide these k specs right which they can help and this can help them and then they can embed in their code so when you go to editor.swagger.io you will find this whole sort of an example which is listed but this example is rather complicated for beginners so i thought maybe we can create a simpler sort of video where there is more you know from basic we will go and see how we can do with this okay so let's get started right i'll just clear the editor so basically swagger just bit introduction so basically api is everyone is building uh can have different structure each api right there's no standardization so then this group came up with the standardization uh which helps humans to consume the api better and also in the machines they want that this api spec or this swagger uh spec or documentation should work right so they have sort of wanting to uh automate the whole thing so you have an api you just give the ml file which is file which is produced by this editor so we will write yaml also only in this black box and in the right side you will see the output right so you give that tml to a machinery machine can do the automation for you so that is an advanced concept so uh for humans also there was no standardization so they came up with that so we'll just make a simple api spec here and see how we can also create for our own api okay uh first there are some sort of fields that they have defined right so open api is the first field that you have to enter and also you can look at these fields swagger specification if you go right all the fields are mentioned here right what fields you can use right and some fields are required like open api is the required field info is the required field and parts only these three fields are required rest you can see are optional right so i'll also take a very simple example not go too much deep so open api this the api version you have to mention uh then we said info write in info you can mention the title so i'll just create a dummy api for learn21 right and some description um learn api learn now 21 api docs right and also you see this editor guides you says should have required version properties so version should be there without version this is not set right and some errors are also coming so it says required path right because paths is a required field so it's saying that path should be there right and maybe just make it more font i will increase so you can see once i am writing here some kind of text is being displayed here right then you can also have contact and give your contact so whatever email id you want to give you can give right and name also you can give okay so as you can see here the api specs are being created now open api info we have now next important is the path right so path uh here you have to mention all the parts of the area or what we also called the end points right what are the urls that can be hit which are sort of a functionality of the api right every api is a get post and and different kind of paths right so all those parts you have to mention here which is the most important thing right so i will mention a simple uh say uh slash course and uh course id slash course i'll just say stash course so this is a path uh for getting the um all the details of the course right so plan 21 has a lot of courses so if i want to get detail of a course i can call this api right and then i can say this is a get endpoint right and once you write that you will see some documentation already uh being created right get you can give some description to fetch details of a course right and you can see uh some error also it says responses should be so every um sort of path or every this http verb should have some responses i'll add some responses right response is the http response so say this 200 response what what you have to do right um you can have content type content application json right so i've been doing this for some time now so i remember these uh sort of uh different fields but you don't need to remember that you can always go in the documentation and see sample examples right here lot of examples they have given right like something like this right what is the description what are the responses to under description content and uh then the schema right and also yeah this language that i am writing here is xml right very simple language uh uh even more concise than json you can also write in json but default for swagger is reaml and can be easily written here okay so application json this is the content type and then important thing is the schema in what schema you will return the results so for that they have a different system where you just define the reference here not the exact schema you can say component schemas and the name of the schema say course and then there is another field uh components where you can define this right schemas and here you can define the course and the different and sort of fields in the course right i will come come to that as well uh here you have to define the course uh what are the sort of parameter here again uh if you are confused anytime like what what will be the sort of uh how you will use it you can always come back and see here right you can just say schemas um like this data model schema is here right okay we want the example of the component so we can also swagger components example all right component section so you can define uh like this so uh schema course is yours uh this and uh then i'll just copy for quick sort of so here you have to define what kind of object and what will you return and say i will return the title of the course right and i will return the description of the course and uh maybe the id of the course night bit uh it will take some time for you to get used to this uh formatting or the field names for swagger but uh once you sort of make one or two documentation then then it will come to you naturally write some sort of this also it gives right it says it was declared but never used what i have used here not sure why is it saying this description is missing okay all right so it guides you as well 200 response to the second right and just make it a little less so here you can see whatever we have mentioned to fetch the details of the course no parameters so i'll add one parameter here right uh because and of course some codes you are getting you're not getting all the courses right so you will have to pass a either a query parameter or a path like path parameter right and here in the response you can just see right components i think there's a hash also right okay now it's good so in the response you can see uh that uh just a minute i'll make it a little larger the response you can see that you will get the title description id of the course back right the only thing missing is parameter so parameters can be parameters can be of different types right parameter can be a query parameter uh it can be a path parameter which is more on the url right so parameters also you can just parameter object uh right here you can check the parameter object uh which where the main properties that you have to mention are the uh the location and the name right so we'll add some parameters also to this get right so we can say parameters right and uh and if you want to define arrays in ml you have to give like this dash and name say course id right and uh type i can say path okay uh in location is in right in path in path okay great and it says something should have either schema or content property okay then as a content application right some issue just go to parameter or just simply i'll say my integer this is also fine let's not complicate it what we are saying is this is a path parameter right that we are wanting to have and the name will be course id and it will be passed the path so sometimes it does not work just refresh the page right here now in the parameters you can see course id is there integer is there so in the path uh you have to mention a course id maybe i can write here as well let's see so this is also fine here you think that course id has to be passed as a parameter in the path uh which is an integer and this kind of response you will get right of course this is very basic the real scenario will have much more details uh maybe some header parameter also is there uh right so it is required or not we can say required to see this uh on sort of editor only guides us so when these are required to then we get this kind of star in red right so on this sort of somebody's looking at this api knows that i have to pass the course id right and in the response i will get like this and similarly more parameters you can always add like header key uh api keys there that you will have to pass in the header okay let's take an example for uh post also and uh then we will sort of close this small tutorial right if you have more doubts you can please let me know and then i'll make further tutorials right so similar to get right we can have a a post but the url uh might be different so what we can do is make another path and this direct uh course right so this is a different path uh this is a post and i'll just add description uh use this api to create course right hosts are for uh creating data or posting data you use this api to fetch details some more sort of description i'm adding right always have to think from the customer perspective uh when they are using the api now responses again it says uh so very much similar uh to uh to the get but the only change will be the request body so this will have another sort of field which is called request body right where you can uh define all the how this data should be sent right uh in the request body um same similar parameters you will have to define you will have to define a schema how right data has to be sent so let's say request body like defining this body i think i've searched this before so yeah so i'll just copy it for faster sort of because i don't remember these so in the request body also you have to define a description say uh post uh structure of a course right is it required yes required contenders and schema again um i think you can use the same schema here as well right because that will remain the same so you fetch a course it has three fields create a course through api should have only three fields as well right and in the responses you can just write this 200 response right and now see every error is gone and you can see a post request as well so use this api to create a course there's no parameter and this is the request body right you have to post like this json and uh responses in in response you will get 200 sort of response or you can just say course created successfully this is very uh interactive right so i changed here very fast here you can see the response changing right sorry not this that one created successfully and schema is also here right title description and id you can also have the required property here uh to uh i think here you can add that as required to no should be an area of property within the schema object okay no problem so that uh we can see how we want to add that right so this is a simple example uh where we sort of saw what are the basic fields that we need for creating open api spec or swagger spec for our api so three main fields are there open api info and the paths and then we added some sort of paths we added one get path right to fetch a course right and a post path uh to post that course right so this is our api small epa spec where we have parameters we have responses and here in the post we have a request body and the responses as well and the schema of the object that we are trying to create and you can generate different kind of html also if you want to share uh with anyone as well so yeah this is small video on swagger editor very nice you should check it out if you have an api and want to create interactive documentation which you want to share with others internal team also right and uh and then see how people use it right which will help everyone get on the same page so yeah that's it uh for more such videos please like and subscribe thanks

Channel: Learn21 Academy

Views: 41,938

Keywords:

Id: rkk2h6Tra9A

Length: 19min 37sec (1177 seconds)

Published: Wed Oct 20 2021