Modern Python Projects Transcripts
Lecture: REST API documentation
0:00 Now a days, a lot of projects are built based on micro services,
0:03 so there is a chance that at some point in your career you will be building
0:07 a rest API, rest API supports a set of standard http request.
0:12 For example, you can send a get request to get a list of users.
0:16 You can send the post request to create a new user or delete request.
0:20 to delete that user, when you are building a rest API.
0:24 You can use a tool like swagger or re doc that will automatically generate a documentation
0:30 for your rest endpoints. So in your code,
0:33 you just write the get post, put, delete and so on methods and those tools will
0:39 automatically create a page that list those end points.
0:44 Let's see an example. So if you go to the swagger UI website there
0:49 is a live demo page, and this is how the restAPI documentation could look
0:53 for your project. So all those things here are end points where you can send
0:58 the rest request, and here you can see what parameters are required,
1:03 what are optional? What are the response calls,
1:06 and so on? There is even an option to try it out.
1:10 So you can add it this,
1:11 Json, and then execute the query.
1:16 And here we have the response.
1:19 It's the same with Redoc. We have the same example of pet store,
1:24 and here we can see the same thing.
1:28 So documentation about the parameters, example
1:32 Json that we can send to our rest endpoint and the responses that we can get
1:37 back, If you don't know what rest api is all that might look
1:42 confusing. But when you actually build one,
1:44 those tools will be super useful.
1:46 For example, if you are working with some front end developers who are using react
1:51 or vue Js and they want to see how they could get data from the
1:55 backend, you can just point them to those you or else,
1:58 and they will be able to see all the documentation for themselves.
2:01 Some frameworks, like fast API,
2:03 include those tools by default. So when you build a fast API application,
2:09 you can go to this /docs, URL.
2:12 And then you will see the rest API documentation generated for you and the same with
2:17 reDoc, with other frameworks like Django rest framework,
2:22 you can install them as a plugin, for me
2:24 It's super convenient to use a tool like that, because each time I change something in
2:29 my code, all this documentation will be automatically generated for me.