Build a Pizza delivery API with FastAPI #14 | Document the API with Swagger Using Doc Strings

hi everyone welcome back to this video in this video we're going to look at how to document our apis with swagger so we've been most of the times using our mini documentation right here and it has helped us to implement most of the routes that we need in this video you're going to look at how to use swagger ui that is automatically generated for us by fast api so if i head over to our browser right here we can see that we have all the routes that we've been implementing for the videos we've been create we've been uh working through so we have all the routes specific to all that as well as those who which are specific to earth so in this video i'm going to look at how to document this in detail so you need to head over to vs code and head over to let's say order routers.pi so within our other routers we're going to go ahead and document the various routes that are specific to making holders so right now we have uh right now we are having our route so to document or how to use dog string so what i'll do is to come right in here and then say i'll write a dot string and then within this top string i'll go ahead and document this particular round so to document it what i'll do is to write in form of markdown so if you don't know how to write markdown and this is how we write it so for example may document this route as let's say a sample hello world route and then i can give a simple description so let's say this returns hello world so if i save and head over to our browser when i refresh when you go to that specific route you can be able to see that our documentation has been displayed so let's go ahead and also try to implement the rest of the route so what i'll do is to go back to our vs code so we're going to go ahead and uh document each route so what i'll do is to come the first route i'm going to document is that one of creating an order so we need to come right here and the right at writer.string now within this dope string i'm going to go ahead and uh i'll place an ahead name true and then what i'll do is to come and say so this is going to be for placing an order and after doing this then i may specify the various fields that we shall create so i'll say this this requires the following and then what i'll say is we need and in this case i'll say that we need uh actually let me go to schemas.pi so schemas. is going to give us a good picture of the various fields that you shall need so in this case we need a quantity and a pizza size so i'll do in here is to come and say that we need a quantity it's going to be quantity sorry for that and this is going to be an integer so i'll specify here this is going to be an integer we can also say that in this case we're going to also need our pizza size so in this case i'm going to also say these are size and then this is also going to be a string so if i save this when we head over to our swagger ui and i refresh when i go to the router of placing an order right here we have uh these various fields so in case you are to carry out documentation of every route you're going to be writing this map down specifying which fields that are required to be input in that specific route this is helpful for people like front-end developers who may need to know which fields are required and what is the max length what is the mean length and stuff like that so let's go ahead and try to implement all of this so i'll do is to come i'm going to simply copy all this and i'll go in and paste it in a new route so right here we have a listing all that so we need to come and paste this and this is going to be a list list all or does so right here what i will do is to come so we have something here i'm going to fix this and after fixing that and the next thing we're going to do is to check out what this route does so in this case we're going to see that we are required to access this route when we are staff members or super users so this is going to return all orders so i'll do is to just come right here and while there is to say this lists all orders made for so for super use actually let's say this list all orders made it can be accessed by super users so in this case we can be able to document this route like this for example it can it lists all orders made and it's only accessed by super users so this then shows that front end developer that you know that access this route you need to be logged in as a super user so let's go ahead and document another route so i'm going to go to one that is for uh getting an order by its 80 so i'll do the same thing i'll put a dot string right in here and in this case what we're going to do is to basically come right here and we first fix this so what i'll do is to say that this is for getting an order by its id so i'll save yet get an order by its id and after this i'm just going to come and simply describe what this route does so in this case what i'll do is come and say this gets an order by its id so let's see uh so in this case we uh we see that the current user has to be also a staff member so i can also go ahead and specify that so i can say and is only accessed by a super user so right after doing that i'm actually going to go ahead and document another route so in this case we have getting used as orders so this can be accessed by uh both supervisors and current and uh normal users or customers so i'll do is to come right in here and what i'll do is also do that so i'll paste that in and then we'd simply call this uh get current users order so in this case it's going to be for getting your characters as orders so i'll go ahead and provide the description so i'll say this lists the orders made by the currently logged in users so right after doing this i mean to fix this and then we have done with uh documenting that route i'll do the same thing for this getting a specific order so what i'll do is to come and paste in this uh this dot string and i also come and do the same thing so i'll do is to come right here and then this is going to be get a specific order by the currently logged in user so in this case we're going to say get a specific order by the currently logged in user so right after doing this then we're going to specify that this returns an order by id for the currently logged in user now after doing this i'm going to save and head over to another also in this case the route is for updating an order so in this case i'm going to come and update an order so this is to be accessed by all users i'll put a drop string once again and fix this and this is going to be for updating and order so i'll call this updating and and all that and then i'll go ahead and basically describe the various fields that we need so i'm going to say this updates and order and so i'll say and request the following actually let's say requires the following fields so it requires a quantity uh an integer and a piece of size which is a string in this case which is a choice just like we saw for the previous videos so let's see if there are any other fields that you can basically specify so i'll go to the order mode once again and we have uh the quantity and pizza size we also have a specific route for updating that status so in this case i'm not going to document it in this route so right now i mean save and when you go to another route i'll do the same thing so in this case we're updating on all the status so what i'll do is to come and provide the dot string once again so in this case what i'll do is to come and basically remove this so this is going to be for updating and all that status so what i'll do is say update and orders status and i'm simply going to fix this and here what i'll do is to come and say this is going to be this is uh for updating actually what i'll say this is for updating updating and all that status so what i'll do is say this is for updating and orders status and uh requires the following field so in this case what you shall say and request so what i'll do is to call this that so in this case what i'm going to say is and this request so i'll specify it requires the order status and this other status is a string so i'll say so i'm going to close this so uh which actually i'll just say in string format so after doing that then we have only one route for deleting an order so i'll come and also do the same thing i'm pasting a dot string and then i'll say this is for deleting an order so i'll just go ahead and delete an order so this uh deletes an order by id so i'm going to come again and describe this so i'll say this deletes and order by its id and i'm going to go ahead and fix this indentation so after fixing it now if we uh to go out we are also going to go ahead and actually document our our rx for authentication so i'll go to auth routes and right here we have a specific route so we have one for creating a user one for logging in and refreshing our token so let's go ahead so i'll start by documenting this so i'll do is come past this box string right in here and the first thing i'm going to do is to so this is going to be for example hello hello world route so and then i'm going to do the same thing for the one for signing up so i'll come i put in the top string right here and this is going to be for signing wrapper user so actually i'm going to say i create a user and this will require the following so i'll go to schemas.pipe and what i'll do is to copy the example right here so let me copy this example here and then go to all throughout so what i'll do is to say actually what i'm going to do is to come and specify this so i'm going to put this in these back ticks and then paste this in so we're going to require the following we're going to have username so what i'll do is to actually come right in here so i'll say username which is going to be an integer so the email which will also be a string so the password which will also be a string and we also have this staff which is going to be a boolean so in this case let's say we have our staff this stuff equal to our boolean we're also going to have our is active which is going to be a boolean so i'm going to remove these quotes also remove these squats i'm also going to fix this so right now we have uh documented this route for creating a user so while this will also do the same thing for our login route so the login route requires a username and a password so that's going to be pretty straightforward uh what i'll do is to come actually i'm going to put this in dot strings so so i mean put this in dot strings and we fix this indentation so right here what i'll do is to actually i put in so i'm going to come right here and what i'll do is to specify so this is going to be a login a user and this is going to actually this requires so what i'll do is to specify this so i'm going to put this in practice so i'll see how this will look in a moment so one what i'll do is to remove this so i'm going to remove these quotes so once i remove the quotes i'm also going to go ahead and just simply specify the type so this is going to be a string and we also need the password so i'll remove the email i also remove these extra fields and so the password is going to also be a string in this case so i'll move the comma and right after doing this uh we are done documenting our our login so i'll go ahead and also do the same thing for our refresh token so the refresh route is going to require us to provide a refresh token so i'm going to go ahead and document this so what i'll do is to come right here actually just create a dot string so within this lock string i'm going to just specify that so this is going to be for refreshing actually i'll say create a fresh refresh token so i'll say this creates a fresh token after actually i'll say this creates a fresh token and it requires and access token actually this requires a refresh token for us to be able to generate a fresh touch in our new token so i'll say this requires a refresh talking so let's say uh when i go back to our login so this requires username password we can also say and returns ah token pair so that again pair has our access and refresh so when i accept this we're going to go ahead and see our documentation now guy so i'm going to head over to our browser and when i refresh we have the various routes now documented for example if you go to the sample hello world route you have a simple description for that if we went to the saying approach we have a sample description as well so if we go and check the other routes we have uh other sample descriptions made so in this video i've learned how to create a simple swagger documentation or for first api thank you for watching guys and if you would like to document your apis in detail uh feel free to write your custom documentations in your so i'll get ui thank you for watching guys and see you in the next video bye you

Channel: Ssali Jonathan

Views: 64

Rating: 5 out of 5

Keywords: fastapi, fastapi tutorial, python fastapi swagger, fastapi python tutorial, fastapi swagger ui, python fastapi, fastapi python, fastapi swagger, swagger, fastapi example, fastapi full course, fastapi swagger ui documentation, python fastapi course, python fastapi example, fastapi oauth2, fastapi crash course, swagger api, swagger-ui, doc-strings fastapi, fast-api api documentation

Id: K8XUR1N--L0

Length: 19min 9sec (1149 seconds)

Published: Thu Sep 16 2021