API Documentation with Swagger and Redoc | Learn Django REST Framework #16

at this point we've been able to develop most of our api endpoints and we are going to document our api so that we make it easy for developers who may want to use it to be able to document or carry out different functionalities within their applications now these applications may be react or view applications and they may also be mobile apps with built with various technologies in this video i'm going to be showing you how to document our api so we need to be looking at two approaches to do this so i'm going to start with one that's inbuilt with django rest framework and that is our browseable api so when you go to our api right here this is our localhost 8000 slash post we are able to see the various api the various api endpoints and the data that they return and we can actually see a very interesting way of documentation so you can be able to see what we gave us the name for our endpoint which is post list create you can also see things such as the description you give and here we specify that this view is one for creating and listing of our posts so we can be able to see the pagination that actually created and the count of the number of objects that we have the next url which is our localhost data and slash post slash page 2. we actually seen seems like my server is down so i'll go ahead and run our server again so when you head over right here and you try to refresh we now see that it's actually returning our page two and you can be able to see the various things the various the various data that's returned by this endpoint we can also be able to check out our pagination here so we have this is page number two we can go to page number three page number four and so on and so forth we can also be able to access other endpoints for example if you wanted to sign up we can go to our slash auth sign up and this is going to take us to where we provide our email our username and our password so this actually uses our serializers to generate for us such a beautiful ui to work with in our development now this is wonderful i've been using insomnia in our videos and that's why we have not been able to use this but let's see if we created the user let's say john doe one two three and let's see if we give them it's actually the email so i'll say john doe one two three at app.com and then our provider username has john doe one two three at app.com so if we provide our password i'll provide our password so this is actually returning our password as his plain text stream but you can also be able to change this or provide that password as password one two three now when i send this we can be able to see that our user has been created successfully and this is actually the response that we get right here so this is one way in which you can be able to document our api however this comes with its own disadvantages because we need to access the different urls on our specific api and it's also not that much user friendly and that's where the drf yes comes in so there are very many ways to document our api with swagger and other tools but drf yes stands out because it provides for us documentation for our api using swagger and redoc that goes deep to document our api endpoints and we're going to be looking at how to use it so i'm going to go to i'll leave the link to the documentation of the rfps in the description and let's get started so what i'll do is to head over to our documentation right here and the first thing i'm going to do is to actually install it so i'll just come and go to where we have our introduction so it requires us to have january's framework jungle python so i'm going to go ahead and basically go where we install it so install it with this command right here i'll copy this command and all i have to do is to stop our server control and see so i'm just going to come here and create some more space so do that with ctrl and b and then what i have to do is to paste in our command so this is going to install our drfs with pip hello and once our installation is done the next thing we need to do is to go ahead and refreeze this to our requirements so txt so i'm going to do clip freeze and then point to our requirements so txt once we've done that then the next thing is going to be to set up a jungle restaurant mark to set up our dirf yes so i'll just come to our installed apps and we shall have to add the following so we're going to add our jungle.contrib.static files and then our drf years now this is important because this is going to actually depend on static files during our documentation so when you go within our install apps i'm going to begin by adding our drf yes and once i've done this then we i also want to check if jungle.com the static files is existing and that is existing within our installed apps already so we are safe now when you go in our urls.py all we need to do is to add the following so just copy the following code and then go to our main urls.poi i mean the project specific urls.poi so when i go within our project right here and go within our urls i'm going to just paste in this code and once you have this code we can be able to see that we have some of these inputs and we also have this code so what this code is is basically how to set up our drfs and we also have a list of url patterns now what i mean to do is to just make this one list of url patterns and i'm going to basically import our ra path since this is using regular expressions now just come at the top right here and all i have to do is to import our path and i'm going to save so when i save we're actually having no errors for now and one thing i'm going to change is to change our url for our swagger so in this case i'll just change this so that you can be able to access our documentation on our home page so i'll just come and change this to path and once we have this as our path so i'll change this from our regular expression to our path and then we are going to have our view and in the name of that specific view so in sf i'm going to check if our server is running so it's not trending i'll pick i'll start it with python money.pura and then run server so this is going to start our server so when you go to our localhost 8000 we're now going to see our apa being rendered via this beautiful documentation so right here we have the different api endpoints that we are being able to that we have for our api and they are being documented in a way that's very easy for us to see we can also be able to authorize and be able to login into our api but now we have basic authorization which are going to set up in a minute so let's try to actually create some some through basically send some requests here so when you go to the slash post endpoint you can be able to send so here we actually need a page number the paginated result set which is the page so can provide the page so i'll say try it out so here i can provide the page number so let's say i want page number two and let's say the max page says and this is going to be three so when i execute we actually see our number of posts which is three posts and we actually see the topic that's being returned is page number two so this is wonderful this is amazing so another thing that's very important here is we need to document most of our api endpoints so i'm going to be showing you how to do that with drfps and you'll be able to document some of the other endpoints for the apa so i'm going to go within our posts and that's actually going to happen within obvious and what i'm going to do is to go within our posts app and within our business for our post app i'm going to begin documenting all our api views so i'm going to be accessing some very interesting utility that makes it easier for us to document these views and that is the swagger auto schema so i'll just come right here and all i have to do is to save from from drf yes so actually going to be drfps.utils we are going to import our swagger photo schema and this is going to allow us to document the various endpoints so the way we're going to do that is by coming right within our api views so i'll just come right here and let's say we have a api endpoint for getting all posts we can just come and decorate it with at swagger auto schema and what we shall do is to pass in a different thing so i'll begin by providing an operation summary so we can have the operation summary and then let's say this is actually responsible for listings all posts so once i do this i'll save and when i save it's actually going to go back and when i refresh so when i refresh here you can be able to see that our url is being documented so you can also be able to provide some other detailed info so we can just come and say operation description and let's say returns a list of all posts so once i've done this then i can come right here and refresh and then when you come back here we actually see that you have a description here that's saying that this actually returns a list of all the posts that we have in our database so this is amazing so what i mean to do is to do the same thing for some of the other endpoints so i'm just going to come right here and copy this and go ahead and basically document our api for creating a post so i'll just say that we are going to create create a post and we're going to say that this is going to create a post so i'll just say this creates a post this this endpoint creates a post so i just say this endpoint creates a post and actually let's just say that we are going to create a processor here just going to say create a post so i'll save and when you head over back here so here we can be able to see it's actually not working so it seems like we have a problem here our indentation so when i save go back here when i refresh it seems like we still have a problem so let's see actually for creating a post permission schema create a post this endpoint creates a post so let's try to refresh here so when you go where we actually have we now have create a post and this creates a post so it can provide a default uh descriptive description for this specific api endpoint so when i go right here i can actually do the same thing i can just copy in our swagger auto schema and then provide that as uh retrieve post retrieve and individual posts so i'm just going to come and say this retrieves and the post by the id and then we can come here and say this this retrieves post by an id so we can do the same thing for the other endpoint so i'm just going to copy this and do the same thing for where we update our posts so can just come here and say updates post by its id and then let's say here we're going to just say this updates our post given the id so i'll do the same thing for deleting and pasting a swag auto schema here i'll just say delete a post and here i shall just basically specify that this endpoint deletes a post so when you go back right here i'm going to be able to refresh so when i refresh we now see that our posts our endpoints have been documented so we have listing posts it's actually it seems like we have a problem here i'm going to refresh again i will now see that our api endpoints have been documented so i'm going to be documenting the rest and we shall be able to continue so i'll just come right here do the same thing here so here actually say getting post for all users so i'm going to come here and also document this one for getting listing posts for an author so i'll just come and say that you're going to use uh sugar auto schema through list post for an author i'll just come here and say that you're going to list posts for an author who is a user and we shall have this same documentation on our apa or swagger ui so it seems like we have a problem here so let me check what is wrong so let me try to refresh so it seems like everything is working fine so let's try to actually go ahead and document the other endpoints so what i'll do is to go to our account app as well and within our accounts app i'll go to obvious and within obvious i also begin by importing our auto schema so i just come and say from drfiask.utils i'm going to import our swagger auto schema and once i've done that and i'll come right in here and all i have to do is to provide so this is our api endpoint for creating a user account so i'll just say create a user account and here we shall come and also specify that this route is for signing up so i'll just say this signs up user so once i have this thing i'll go ahead and do the same thing for our login endpoint or i'll log in url overview so here i shall just say that this login or let's say generate jwt jwt pair and here we can see this login users with email and password and when i save this so when i come back here i'm going to refresh so it seems like we have issues but when i refresh here it's actually going to work so we have generating a pair so we're actually going to also basically document other endpoints so now come here this is for post and this is actually going to be for getting a user's information it's actually going to be uh get uh request info just like we explained for the various previous videos and this actually shows that request information so when i save i'm also going to do the same thing for so this is actually for our login endpoints so this is i think we are done for our authentication endpoints so when i go ahead and refresh we now see that all our endpoints have been documented now you can be able to check out the various ways of documenting an api with drfps i just want to talk you through the basics another important thing is actually how we may be able to login into our api and we're going to be looking at that so in the documentation right here we're going to go to where we describe our authentication schemes now if you've checked out some of the previous videos we were actually using the bearer authentication scheme to login into our api so i'm going to be showing you how we can use this drfps to basically state how we are going to set up our authentication schemes so within our swagger settings and this is actually this is actually how they are telling us that this is how it allows us to describe our security definitions so we have our sweet swagger settings and this is what we are supposed to add to our settings dot py so i'm just going to come and copy this now when you go within our settings.py that's within a project folder i'm just simply going to come and add this settings dictionary so this is going to provide for us two types of authentication or to security definitions and that is the basic type which allows us to log in with our username and password as well as our bearer authentication scheme now in this case we are going to use our brs so i'm going to get rid of the basic and here what we can notice is we're going to be using an api key and we're going to be accessing our or providing our api it's going to be through our authorization headers so this is what this is actually all about i'm going to go ahead and save so nsf and head over back to our documentation right here when i refresh we now see that we have our authorize and here we have our authorized that's basically telling us that shall have our value as bearer and in the api qr access token so i'm going to close this for now so another thing we're going to do is to actually change our authentication so i'll just go back right here in our settings and what i'm going to do is to get rid of this token authentication so that we use only jw2 authentication now i'm going to save and myself i'm going to refresh and now we're going to see that we're using our we're going to actually be requiring to use that jwt authentication now another thing we're going to be doing is getting our api token and then logging in on our swagger ui so they're going to do that is first creating a token so i'm just going to come and log in with the user who is currently logged in so i'll go right in here to our token obtain pair view you need to check out the jw authentication video so i'll just go ahead and try this out so i provide an email for a user who is existing now let's try john doe this is going to be john doe at app.com and shall provide that string password now this is going to be our password which is going to be password uh one two three so when you try to log in or execute we are actually going to be seeing our access and our refresh token so i mean copy our access token right here and i copy our access token i'm going to go right within uh authorize i'm going to click our authorization button and then i'll come and provide bearer and then our token so when i click authorize we're going to login into our api so let's try to actually create a post so when i go to where we create a post i'm going to go and try this out so when they come here i mean provide our title as sample title and in our content has sample sample content now when i go ahead and execute we're going to see that our post has been created on this endpoint that has actually been protected now i've been able to successfully login into our api using our swagger ui now this one way is very helpful as it makes it easier for developers to be able to understand the different endpoints and what they do i'm going to leave the link to the description so that you can check out how to use drf yes another thing that comes with their fps is actually the the redox documentation so if you went to localhost 8000 and any access slash redoc we can be able to see the different api endpoints generated for us or documented for us in such a manner now this is the beauty with using our drf esque for our api documentation now to summarize our api documentation i'm going to go through where we set up our drfps and change some things so i'm going to go within our urls that's within our main project two articles i mean close those and when you go right here i'm going to go and what i have to do is to change our information so we're going to change this from snippets api to blog apa and this is going to be our version one so i'll change the description to this is an api for blog or let's say this is an api for a blogging application and then we can have the terms of service or remove them you can also have the license but i'm going to remove that so that you just have these three things so when you go back to our api right here and refresh we actually see that our documentation has changed and when you go ahead and refresh even on our swagger ui we can be able to see that our documentation has been able to change in this video i've been able to talk about our api documentation using the browser api as well as our swagger ui and redoc we've been able to explore drf first and some of the features it may provide for us that may help us to document our api to various developers who may need to develop front-end applications with it thank you for watching this video if you've liked it please leave a like don't forget to subscribe if you're new thank you for watching and see you in the next video bye

Channel: Ssali Jonathan

Views: 7,291

Keywords: swagger, api documentation, documentation, redoc, swagger api, open api documentation, swagger ui, api, rest api, swagger documentation for rest api, spring boot api documentation using swagger, open api and swagger, restful swagger documentation, rest api documentation, auto generating api documentation, best api documentation, distributed api documentation, api documenation, consume swagger api c#, api gateway swagger integration, drf-yasg, drf_yasg django rest framework

Id: NVlebOJkzKE

Length: 25min 50sec (1550 seconds)

Published: Thu Jun 09 2022