Django DRF Project | API Documentation with Swagger UI | 18

hello and welcome to the Django drf project  e-commerce this tutorial is part of a series of   tutorials which you can watch for free the link  to the YouTube course playlist is in the video   description this course is also available on udemy  where you can watch the course ad free download   the tutorial source code and access all updated  tutorials and playlists the link to the course   which will always provide the best price can be  found in the video description to ensure that   other developers can utilize this API we are going  to be developing the documentation as we develop   this application throughout this course building  our API documentation is really a straightforward   process once we have set up the tools which  will automate the process here in this course   we are going to be utilizing drf spectacular  and Swagger UI so there are two components here   and essentially What's Happening Here we have  drf spectacular which is going to essentially   collect all the information about our API and put  that into a format which can then be utilized by   a front-end package in this case Swagger UI and  present that information to the other developers   or anyone who wants to interact with our API this  is the package on pipei so DRS spectacular that's   what you're looking for if you're interested  in having a look at the documentation then head   over to Pi Pi or just type in drf spectacular  into Google right let's go ahead and install   so back in our application let's go ahead and  just close that make sure that we're in the   right directory yep right so uh let's go ahead and  pip install drf spectacular there we go right okay   um my vote okay so people still drf spectacular  and there we go right so that's nicely installed   now we need to add that so I'm just  going to actually add that first to   the new document here so let's just updating it  the commands for this section of the course so   one point 0.1 commands you'll find that with the  where you'll find the source code for this course   um or you'll find it locally in the tutorial  you'll be able to download the resource so let   me just update this so we're going to install drf  spectacular we've done that let's head over now to   drf and then settings just need to register this  so the base now this is a type of package which   maybe you only have running locally potentially  but maybe not um so I'm just trying to emphasize   the point that maybe some of these packages that  we still install will just be for development   only so we may want to add them to the individual  modules Here Local or production but let's just   continue as we are because really it was just a  just a drop in an idea in regards to modulizing   settings but we'll focus on that later when it's  really required when we're actually deploying the   application so this is an external package let's  uh add this in so drf spectacular so there are a   few different settings that we can apply here what  we need to do is we need to register a spectacular   um as the auto schema or drf so let's go into our  settings at the bottom now we had already created   our rest framework in preparation here for our  settings so let's set the default schema class   and we just need to set that to a drf spectacular  so dearest spectacular dot open API Dot Auto gamer so what we can do at this point is also add  some additional metadata so that's going to   be in the spec Tech Euler settings so it adds some  additional metadata so for example and this will   make more sense you'll be able to see this where  this is going to be placed but let's just add a   title to begin with let's call this project Django  drf e-commerce so we just add a title for now and   add a comma there to bring that down okay so  we just add the title for now and yeah that   do for now we can add some more things later  so the that's how to set some of the settings   now of course you can check the documentation and  you'll be able to see all the different settings   that you can apply here but let's just get this  working first so with that done now let's think   about how we're actually going to be able to  create our schema because what we're going to   do is we're going to create a schema so we're  going to use like we said in the introduction   we're going to use DRS spectacular to actually  build construct a schema and that's going to be   a file it's going to generate a file and that  file is basically going to be a map of all the   different interactions that were possible within  our API restful API and then we can utilize that   information to display it in a web interface right  so now everything is installed and we have a basic   setup let's go ahead and actually build our schema  file let's give this a go so let me just bring   that back in let's go ahead and just clear this so  to do this what we need to do is what's going on okay right so what we're going to need to do here  is use match.pi and then we're going to need to   initiate spectacular so spec attack you sort  of attack you la and then let's now save this   to a file called schema dot it's going to be a  yaml file okay so no module name drf spectacular so if you go back into the base if you do  receive this problem you've simply just   renamed it incorrectly um as like I've done here  so it's not drf Dash it's going to be underscore   apology so in the base settings here I'm just  going to change that to an underscore so let's   try that again so manage.pi spectacular create  a new file called schema.yang okay so this time   we'll get an error here default schema class  module module not found no module name drf   spectacular so this time it looks like we now have  an issue maybe a typo down here in our settings   and it's the same problem apologies so it's not  a dash there it's going to be an underscore again   apologies right so that has changed there in 901  in our base settings so drf underscore spectacular   so let's now give that a go again and this time  it does look like it may have been successful   so you can see here on the left hand side this  schema file now appears there are no warnings   um there may be four errors here um that's not  a problem at all and we'll go through why that   is shortly we might need to change some of the  settings here so for particular views it may   have problems actually finding or generating the  information that's required there's no problem   at net for now we'll do that shortly but just the  fact that we looks like we have generated schema   here so we go into this schema and what we've got  here so you can see the title appears that was a   metadata that we added in the settings and you can  see that we could probably add some more version   and so on you can see a path so this is the path  now remember how to get to the category to display   all the categories it was API category so you  can start to see it started to build generate   information about the endpoints that we've  defined within our application within our API   and you can see that it then adds some additional  information about how you would then interact so   the details about interacting with that path now  this is a really simple interface here simple get   interface but some interface which may have for  example other attributes that can be passed in so   foreign looks like we've got some sort of response  it's been tested and some additional information   here now let's just test this out first let's  just go ahead and put this into the UI get the   UI working and then we resolve any of the errors  so I'm trying to keep this in order now I don't   want to forget to add this to my requirements um  I may have not done that yet so let's just add   Dr spectacular to the requirements let's  just keep that up to date so pip freeze   before we do anything else requirements so  that keeps everything up to date so we've   got Dr Spectacular Now in the requirements  we know that the requirements is now updated   right so let's just close down because there's  loads of stuff open here can be a little bit   confusing right so now we're going to sort  out the front end if you like so we're going   to activate the packages which will allow us to  show this documentation in a front end so let's   go into our drf e-commerce drf e-commerce and  we need to go to the URLs so let's find the urls   okay so we're going to need to bring in all the  tools that are going to be needed so from from drf   now let's remember the underscore spectacular dot  views and let's go ahead and import spectacular   API View and we're going to need the spectacular  Swagger view so we're using swagger UI to render   the render our schema file and just bring this  over a bit we're going to stay in the URLs okay   so that's the two packages that we're going to  need so now we just need to set up a path for   our schema so we can actually view it so let's  make sure that we've added this incorrectly comma   yep okay so we need a color right here there we  go so let's add A New Path so um let's go for   API schema um you can use whatever path you like  but let's go for API or it could just be schema   um yeah let's go for API schema to begin  with so that's where we're going to find   our schema so we need to bring in  the spectacular saw or API View   API view um dot as view so these  are views that are built in which is going to allow us to interact with uh  it's going to allow us to interact with our schema   so let's go ahead and say name equals  schema okay so now we've set that up   what we can do now is actually user an API so what  this link is we we navigate to it but essentially   that is rendering if you like or making available  our schema so what we do now is we add a front   end which can access that path and then render  that information onto a front end if you like so   what we can do now is add a new path here now we  call this API slash schema slash for example Docs   so this is where we're actually going to access  and view the schema so this is the Swagger View   dot as View okay and then we need to specify  the URL so URL name that's the name that we've   just generated here that's going to be  schema so URL name equal so we pass in   the schema and then it will then render  the schema data right and there we go   let's give this a go so uh dot h dot Pi let's  run the server let's just remind ourselves so   API schema and then we go to the docs where look  at both endpoints right so back in the server uh   the local loopback address slash API that's  obviously going to take us to the endpoint   here that we've generated earlier so let's now go  into schema now I'm not going to actually activate   this because essentially this is the path to  the schema file if you like so if I went to   this endpoint here this URL it was simply just  ask me to download the schema so I don't need to   look at that so let's go to the last point which  is docs so if I activate that or if I navigate to   that you can now see I'm now displaying all the  information that's been generated in the schema   so it looks like it's collected information  about the schema and also information about   the endpoints and obviously we only have one at  the moment and that's the API category endpoint   so you can see what how to interact with it it's  going to require a get request so it looks like   we can only retrieve data from this endpoint  being that we it only accepts get a get request   so we can use a drop down here and what we can  do is there's a few different options here we   can try it out so this gives us the interface  to be able to actually test out the endpoint so   we can execute and it gives us information about  the actual command that was used to actually run   that request or create that request the request  URL and then it also then provides the output   so this is a response in addition to that there  are some additional information here which can be   useful much later on response headers that can  give us some additional information when we're   trying to maybe troubleshoot so that is a simple  implementation of our documentation that we're   going to be generating it might not seem too much  at the moment but hopefully you're going to see   the benefit of it as and when we start developing  more endpoints as a front-end developer I can   spin up this documentation and I can take a look  and what it's going to show me eventually is the   endpoint and that's going to give me information  about what data I can kind of collect from that   endpoint so if I'm looking for something specific  if for example there is an endpoint here or   a way to interface with the API that requires  me to pass in different parameters then this   is going to give me those details it's going  to tell me what data is going to return what   type of data is being returned all sorts of  useful information as a front-end developer   so you might notice this authorize button  here so if I click on this authorize button   you can see that potentially some of these  endpoints might require some sort of authorization   So eventually we may move into security and  think about that but for now there's nothing   much here to talk about right so going back  to the code if you remember when we generated   our schema there was a few different issues so  let's just replicate that again so just running   and rebuilding our schema here and you can see  that there was Zero warnings but four errors   so unable to guess serializer so utilizing a view  set as we've done here it isn't able by default at   least to work out what serializer we're using and  that's useful information and that will add to the   documentation so let me just give you a resolution  to this problem here so let's go into our document   our project here let's go to the Views so  product views and let's go down to our view set   now some approaches we can use to create views  will explicitly Define for example the serializer   and drf spectacular is able to actually collect  information from that now because we're utilizing   this approach where we're utilizing this list  function here it isn't able to work out which   serializer we're using so all we need to do  is create or just declarate essentially the   the function here and provide some additional  information so it's able to utilize that when   it builds the schema so from we'd bring the  tools drf spectacular d drf spectacular and   dot utils let's go ahead and import the extend  schema you can check out the documentation if   you need more information about it there's a few  different options here but no doubt we're going   to be utilizing a few of them as we move through  this project so at extend schema so we're going to   just essentially just specify responses equals and  I'm just Define the serializers that we're using   so in this case we're actually using the category  serializer so that is essentially telling they are   spectacular what serializer we're using and that's  going to be able to utilize that information to   generate more documentation so let's roll out the  the schema again so we're going to run the schema   and notice that this time it's run there are no  errors at all so everything is working perfectly   so let's go over to the front end first of  all let's just load the server run the server   and just go ahead and refresh and this time  you can now see we have the schema option   down here and what we have is essentially we're  given information about our serializer remember   our serializer it offers these for example fields  so we're given more information about our fields   and that would then give us more information  about the data types that can be really useful   particularly when we're trying to add data  or send data to our API it would be useful   to know what data is required so that's going  to give us some additional information there so   all information is good information so we just  drop that down and again that's probably going   to make more sense once we move into the front  end and start to utilize this information it   may kind of resonate a little bit more as  to why this information is important but   for now we're all set up and as we further  develop all we need to do essentially will   be to keep building our schemas as and when we  add more endpoints and this documentation will   nicely scale we'll keep moving into this and  solve any errors fix any problems that might   occur as we utilize different tools from the  drf toolkit but for now we're ready to move on   before I forget let's also remember  that we will need to add schema.yaml   to the git ignore file so let's just add  that in so that we don't save that to our Source control so just add that over  there so that should now be grayed   out like that so we're not going  to add that to our source control

Channel: Very Academy

Views: 26,723

Keywords: django drf project, django rest framework project, drf ecommerce project, viewset, DRF router, django router

Id: XBxssKYf5G0

Length: 20min 0sec (1200 seconds)

Published: Wed Jan 11 2023