Getting started on how to write node api documentation with Swagger

all right so welcome back to the little coding so in today's video we're going to learn how to document your express api using swagger so as you can see on the screen right here so so first we have a title our documentation this is like the play the route that we can make this execute and so you can see here this drop down of the um api so let's say if you're using the in the local environment you can choose your local host if you want production you can choose select this one and so you can execute right here so see right here we're going to do post request so i can execute and may request so you can see we have create a new user make a respond body and so this one just lists all the user if i click execute right here we have three user and so we do this for the other two and all right so i think that pretty much it for the other let's say for put patch and delete i think once you learnt all of this one you can implement it by yourself it will be your um homework after watching this video and i think that's pretty much it for this one so let's get started all right so before we get started so you can't go into my repository right here list the link in description and clone the startup project which is the master branch right here so for this video we going to focus on writing the documentation for your res api instead of building the api itself so i have made a simple rest api already so you can just clone this one do you uninstall and then join run dave so here i'm using vs code you can use any target that you want and i haven't cloned and installed and run everything already and so as you can see right here if we go into route user so we can see this we have four route get all the user create a new user create a user using query i get a user by querying id and the last one is get user using path and so to make the request to this api you can using postman or you can use the extension in the vs code itself called rest client you can install it right here this one so when you install this one you create the file called dot http and so you can see right here we have this route that run on local 3000 so if you go in right here this is our apps that we get and then then we run on 3000 and to make a request you can just send a request it will return all the user right here and then if you want to create a new user you can uncomment this one you can come here and then this is the payload so you can just send a request and it's create a user and to verify that you can just go back and then get at least all of the user again so as right now it's increasing phi all right so you can see this thing is okay but it would be better like we can just run it on the swagger like i show you on the demo so that's what we're gonna do let's do it so in order to do that we have installed two depend uh one of the dependency calls use uh swagger ui express so as you can see right here so once you have installed this one we're gonna initialize it so let's go into that let's go to apps and so i'm gonna import this one so i import the swagger docs equal to require so it's gonna be swagger express ui and for that i can just app.use so this is gonna be your documentation route so i'm gonna do like okay uh the documentation slash documentation so you can right here you can just select any route you want and we're gonna do swagger docs dot surf and the other one is gonna be the swagger docs dot setups and this setup is going to be all of the documentation that we're going to put inside here for now i'm going to put this one blank i'm going to create another folder on the source right here it's going to be the hub helper and we're gonna do this one i will let's say documentations dot js and this is contain all of the documentation that we're gonna write of for two initials all right for now uh we can break step to write this one first is i'm going to uh conswagger docs is going to be equal documentation is going to be equal to um let's say this one you can do open api i'm going to do like the we can use an open api or we can use swagger so i can i will do like um open api version 0.3 right here and then we can uh give like the info of our of our swagger so let's say we're gonna do like the title of it so the title can be anything i'm going to do like demo and then we're going to have like a version of our api so for our version i'm going to do let's say 0 [Music] 0.1 and so i think that's it for now i'm just we're gonna focus on it we're gonna come back and update this later so export is gonna be swagger documentation okay and go back into our app so we can import this one so i'm gonna do cons swagger documentation equal to require uh it's gonna be come from source slash helper slash documentation and then you can use it which is right here okay so now when it's ready you can go into localhost 3000 and slash documentation so i'm going to go into here so as you can see right now we have initialized this our swagger so let's say we call a demo and we not have any spec yet so we will do it more all right if you're curious uh why i'm writing let's say uh the you can see right here info how do i know that so i can just reference to the swagger editor right here they have some examples to show us let's say as you can see right here we have the info and then this one they're using swagger instead of open api so that's why i told you either here you can use either use swagger or open api it's up to you and so we have the info as you can type here we have version and title and so now i'm going to add a description to our swagger i'm going to add the description so let's say this is our demo videos uh so that's it right so now so to go back you have to refresh all of these things right here all right so i think that uh first our we have an actual already so now next thing is you can set up the server so we're gonna do server so we're right here it's gonna be the array because we can have like a local server or the um let's say production server so right here i'm going to do http slash the route for our local it's going to be localhost 3000 and 3000 i cannot okay and then we have a description again so description right key you can write anything so i'm just okay local dave and if we go back and we refresh and so right now we can see if i have one so that's why we not be able to select and i can just copy and paste this one again let's say i'm just changing this one to just productions and this one is going to be productions dave i'm going to close this one and we refresh again so right now you can see we have be able to select and between two server all right so i think that's great so the next thing is we can do is like to like target i was working to target our route i will pass to our user pass um so what we can do is like going to do half the pass right here this is going to be an object so i'm going to do let's say so right here we can do pass user slash user and so what inside here we can do let's say get uh so we're gonna do get request and for this get i'm gonna do leave it blanks hopefully we can see the gets right here there you go so right now you can see we have this one but we not have like the parameters or what it does description to it and into this one so let's write this one so to go back into the reference i'm going to show you so that later you can learn how to do this on your own okay we have to get right here so you can see right here the text so we have like the tag right here so what is that so the tag right here is gonna group your route into one specifics um let's say groups it so you can see right here in this wagga we have like um a pet groups and then we have store route and like just route for everything that will relate to patch everything that would like to store so we want to do that as well right if you go back in here you can see our swagger is like this one is default so we don't want that so to do that you can create as a text and for the text it's going to be array because we're going to have multiple text into this one so you can name your text so i'm going to name this one i said like a user and we can have like a description about it it's gonna be like a user route something like that okay so right now we go back we refresh and we have a user route but we're not set any pass to it yet so that's why it's empty so to do that it's going to be simple for the get right here going to do like text for this one for to attack of this one is going to be and it's going to be an array as well because each of the attacks okay is going to be an array and we can call like name of attacks which is the user right here okay so you can see it's not to be matched so then if we go back right here if we refresh you can see right now the default is gone and our slash user right here is under the user route perfect so the next thing is we're going to have like a description of our route so you can see right here we have the description and then we can try it out and so to do so we can't uh give a description so we get right here i'm gonna get like the description it's gonna be uh list all of the users and so from this one and then we're gonna have like the response like so right now if we go back refresh so you can see right here we will be slowly getting it so right now you can see if i try it out uh there were probably nothing because we haven't write any response to it yet so if you look at right here this one is how you how you write the response so we have to create the responses and so it can be 200 or 400 depending on what happens with your route so let's do it so right now we're gonna create the response for this point and then we can do something like this the responses so first one is going to be 200 so it's mean that okay this is like the status codes that api your api returned and let's say i'm gonna do another description for this 200 it's like um okay so you can give a difference so it's like at some time it's unnecessary it's not like mandatory to give uh the description here it's just okay um we wanted to like you know if i go back in here i can be able to read what is going on so that's why it it's up to you so so what is the content that we're gonna return so so depend on the api that you're gonna return so our api is gonna return the application json so basically we're gonna return json right and so we're gonna have a schema example of how your api is going to return so for example let's say i'm going to do like the schema is going to be types type of it that's going to be in objects so if we go back into our routes user so as you can see right here our get user is going to return like this json right here so it's better to give the user the example of what they expect to see so go back into our documentation and then type object and now we're going to have like the example and so the example is going to be an array it's going to be an object let's say for example i'm going to do once and for the user is oh i'm going to do empty and then account right here is going to be zero now we want we're going to update this one to be more useful right now we go back and we refresh so you can see right here right now we have like 200 is okay and this is the type return typos this is the example that we can expect from this api so let's try it out right now i try to execute so you can see right here this is the response that make to our api and all right this is what it looked like okay that's pretty much it that's good this one is good for our get api and all right so i think that pretty much therefore i will get so but look uh right now it feels like this one is gonna be messy right so if you're doing this one is gonna be so messy and which is if you imagine if you have 10 routes you're not going to want to put all in one documentation right here so it's a better way is that okay you have your out you you folded your routes and then you can create like a user dot swaggers swaggers.js or swagger.doc is up to you like i'm gonna do like um doc.js and for this one i'm gonna import everything that we write in here relate to the user route so i'm going to copy everything and then i'm going to do it's right here that's wrong and because of we do this one wrong okay so for this we're going to create an an object wrap into this one create a variable called user docs let's say user browse docs something like this so you can see there you go and then uh for this one forget a request so uh we can create another one and create let's say cons get user or okay list user or something like that okay it's gonna be equal to this one and then for this list user you can use it right over here and then for this one we're gonna export this one so module start export is gonna be equal user docs and go back into the documentations we can just spread our user doc yeah this one okay let's see okay we import the right things and if we go back right here right now everything is just still work the same things so i'm gonna import this one it look good very nice um this one i'm going to copy this one uh just to go back into our user doc so i'm going to update rather than the empty user right here i can create a like you know just can't users it's going to be equal to one of the value that we have in here because this is going to be the user record right okay oops i delete too much okay so now i can instead of the empty array i can do like you know array of users so we can do just okay you can do just something like this as well and then we can do users and then we count this one one and if we go back we refresh right now this is the example that we can expect it it will look something like this okay so right now that's good for our this one let's do another one is going to be post so post this one is going to be let's say i'm going to create one it's going to be create user okay then we can try to count right here create users is going to be equal to this one so for this is going to be the same thing so first is going to be like the text for the like you know we want to group this once and then you can try to description so create a user create a user and for this one for post when we do post requests so if we go back if i refresh so right now we need to send a body to it right so because we have to send the data to the api so in order to read so for that we need to have a so we're going to have a request body that a request body is going to be content of it is going to be the application.json so i'm going to just copy this one application.json and inside here is going to have like a schema as well the schema alpha the the things that we're going to send to in our request is the type of it is going to be an object and so it's going to have like a property so it's going to be property and for this property it's going to be name so why its name because it depend on your api if you go back into this uh post user right here we expect you to send um something like you know name something like this one that's why we can reuse this one so it depends on your like you know api so post as well it can be like password or something you can use it right here so the type is going to be strings and then for description of this one you can have a description or not let's get like names of the users and you can have the examples so the example is going to be david okay okay so for this one so right now it's great uh if we go if we refresh if we go come back and you can see right now we have this request body and let's try it out so so try this one and then you execute so which is have nothing to return so we need to have to respond so don't forget about it so we have the request body so the next thing is we're going to have the responses so i'm going to copy this once basically it's going to be uh similar and 200 okay we're going to return this one so when we post let's see what happens if i try to post a new user what's going to return back to me so it's going to return something this back like to me so i'm going to copy this one go back to our user dark right here and then instead of this one we can examples is going to be object it's going to be like user index 0 because as you can see right here this is an array right so let's go back refresh one more time so as you can see right here we have the request body what we expect you to send us and like and also this is um the the the uh example of the response but actually this one if you let's say uh if you change something here it still worked why is that because this is not gonna prevent you like or do the validation this is just a documentation uh user might up you know just to change it but like i said this is the documentation if you want to restrict this you have to do another way i have another video that focuses on writing the express api with typescript so you can go ahead and check that video i'll leave the link in the description as well it so alright so now you can see everything is good for post and get user all right so we have two more routes so as you can see right here we have the uh post get user list all the user already so the next thing is gonna we have create one more route that is gonna get a refining user by its id but it's gonna use the query instead of um instead of like the pass so like get user by query id something like this one okay so let's do that um so go back into our dot user docs and so for this one we can have like uh us something user so it's going to be slash users slash 90 so and then so for this one we're going to do get request and we can just create with one get user by query id okay and we haven't created yet so let's do that okay so for this one basically it's the same thing so uh we can copy this one and then we're gonna have our descriptions for this one it's gonna be like get users by theirs id oops i think i misspelled by the ids but we can summary of this one there's a field one more field is gonna be called summary that we haven't talked yet so for this one if you can re if i refresh this one so it's like the summary that's happened up here here so if the description is like you have to open to see what it's like but the summary is gonna appear on this one right here so now we have this one but for the query the user need to send us some information as well right so for that we need to create the parameters that the users need going to send this to us so instead of post for post we gonna do request body and but for the get we just get the param so if you look at our api right here we can have like request that query it is a parameter it's not like the request body okay so for this we're gonna have um our params and our param is gonna be an array and then we're going to have our name so the name is going to be an id why it's id because this is what we use in our api right so you can see right here or api is like request.query that's why we're using this one okay so we have our names and we're gonna do where is it is it in the past or in the query so we're gonna use query so for this route we're gonna do query and we can do descriptions so it can be anything it's like what is that it's id of the user so make sure you have like you to say what it does and the type of it is going to be what are strings and then the example you can give them the examples so for the example uh you know just the id of it right here so i can just choosing this one and do it right here okay and there you go so right now if we're refreshing this one so right now you can see we have one fields that allow us to try it out and with this information uh when we execute it's nothing because we need the response okay the response is going to be the same thing so you can see i can just copy the response right here and then we can just paste this one and it will refresh so you can see this is what it looked like so i'm gonna try it out let's try it so there you go so since we have the user so if we do not have the user i'm gonna do one and for four we got four four not found because the user not found so we can create this route right here for the 404 as well so if we let's say refresh we can sell this one so you can see we have only status 200 that's going to display something like this to us but if you know for a fact that your route is going to return something else you can write it so if we go back in here our route right here is going to return status 4 4 which which with this one so for that we can just um let's go back here okay so we can't do like four or four and then with the descriptions of this one is going to be like a users not found something like this one so you have more status you can just do something down to it right here okay okay so for now if we refresh right here so right now we have one more status it's gonna be four four four okay that's pretty much it um so we're going to implement one more for our last route so this is the route so for this route what we can do is going to be not we're not going to put under this one it's similar to this one but it is going to be look something like this an id and get user by let's say pass id okay so this is a path this is for query so i'm going to copy actually it's going to be actually it's going to be the similar thing to this one i can just copy and paste this one and then we can replace this one tag is going to be user and we're going to change a little bit of thing is going to be path and descriptions by the id so this one in rather than query we can do that in pass instead and basically everything is going to be exactly the same things right now if i'm refreshing this one we having this one let's try to create this user with this id okay so right now we have this user with this id and if i do once so there you go so this is what it's look like between pass and query so you can see when we make requests the id is the underpass but if we do with this one when i try it out the id right here you can see we have a question mark right here that is from the query so i think that this is pretty much it of what um for this one i just for this video it's just getting started on how to do it and i'm gonna do it uh another video for more in-depth uh for this one so we have like some like enum or for the security for us like json web token or something like that and for this one you can try to make it uh better so right now i'm kind of like duplicated things so you can see some response is going to be exactly the same so i know you can do better so for this video just to show you how to get started for this one and yeah i think that's pretty much it and so the last thing i want to say is that you can go ahead and try check this one and try this on your own let's say for put and for delete and something like that and try to read from here so you can see basically what i do right here is gonna be much exactly the same as we did um for uh this one right here all right so yeah i think that pretty much it for this video i hope you like this one and don't forget to subscribe alright so see you guys in the next video peace

Channel: Daily Web Coding

Views: 7,885

Keywords: api documentation, swagger, api, swagger api, how to write swagger api doc for put request, how to write documents for api, how to integrate nodejs with swagger, rest api, swagger ui, node js api development with swagger, documentation, api documentation swagger, how to use swagger in nodejs, swagger editor, generate api documentation, how to create swagger docs for express, swagger ui with node and express jsdoc, swagger node js, swagger editor generate documentation

Id: sTLJ1mHpsOI

Length: 29min 52sec (1792 seconds)

Published: Fri Jan 14 2022