#100DaysOfWeb in Python Transcripts
Chapter: Days 69-72: Django REST Framework
Lecture: API documentation with Swagger
Login or
purchase this course
to watch this video and the rest of the course contents.
0:01
Alright, we're coming to the end of this chapter and a final topic I want to briefly discuss is API documentation.
0:10
And there's a whole documentation section on the Django REST framework page and looking through this there are a couple of plugins you can use
0:20
and one of those is Swagger which, let me see here. First of all the definition, Swagger's a powerful yet easy to use suite of API developer tools
0:32
and you can check it out at swagger.io. Here in the REST documentation I found this plugin Django REST Swagger and it's pretty neat
0:42
so let's go with that for now and look at the nice interface that it should give us. And the set up was very easy so I went to the README
0:51
on GitHub and we just have to click install it. So let's do that first. Then we just add it to our installed apps in our settings.
1:19
And then to use it, we just have set up a route and to define and get Swagger view. So in our URLs.py or for our API app.
1:33
So first we import get Swagger view then we need to define the Schema view and let's give it appropriate title.
1:52
And then we can just set the URL. And let's make a endpoint called Docs that points to the Schema view.
2:11
Now going through that endpoint, look at that. Looks very nice. And get all the endpoints, I can try them out. You get all my quotes.
2:27
I can get a individual quote. It's a new one we just added in the last video.
2:45
I can delete a quote. Actually I cannot because I'm not logged in so I can start a session and let's try that deletion again.
3:07
And I got a 204, which means the quote is not longer there. Great. Now one final thing. As this is a video on documentation
3:16
and you might be thinking, where's the actual documentation? This is looking pretty bare-bones. Another great feature of the Django REST framework is
3:25
that it's smart about how you structure your commands. So if you go into a class-based view which we have two of and you structure it by API methods.
3:37
So get post, retrieve, list et cetera. The internal mechanics knows how to structure that and the Swagger plugin then knows how to filter that
3:47
and put the right command in the right place here. So let's actually show that and I already have some documentation on my clip board.
3:58
So on the list, create API view we can have a get method that gets all the quotes. Or we can do a post of an awesome new quote. And on the detail view
4:10
we can have get of an individual quote an update or put of an existing quote or a deletion of a single quote. So structuring our docstrings like this
4:24
like how it's recommended in the documentation. Look at what happens to the Swagger UI. So let's save this. Refresh this.
4:37
And look at that. Cool, right? So the list view extracted these two commands and the second detail view extracted those three commands.
4:48
Return, update, and delete. Return, update, delete. And return and create, return and create. So again, Django REST framework
4:57
and its plugins are pretty smart and elegant. And I think that's a nice way to wrap up this video on Swagger documentation
5:05
and this chapter on Django REST framework. So this concludes the video content of this chapter and starting tomorrow you're going to get practical
5:14
and implement your own API.