Modern APIs with FastAPI and Python Transcripts
Chapter: Accepting inbound data
Lecture: Automatic documentation with FastAPI and Swagger/OpenAPI
Login or
purchase this course
to watch this video and the rest of the course contents.
0:00
We're about ready to close out writing code on our API. We're gonna have to deploy it still,
0:05
but other than that, we're basically done. Two really quick things
0:08
I'd like to cover. First, I've added some fake data on application startup. So over here, remember our configure method? We have configure fake data,
0:17
and the idea is that once the app starts, I don't want you have to go keep re-submitting reports just to get something to happen. So now over here,
0:24
when the app runs, it always starts with two reports around Portland, Oregon and then as you add more, they'll show up over there,
0:32
Of course. So that, just so you have it if you're wondering where that came
0:35
from. But the main thing I want to actually talk about, just to wrap everything up here, is notice I've typed out some documentation here,
0:42
and it's fine. We click on it and see stuff happen, and that's fine. But FastAPI is neat because one of its features is
0:50
to integrate open API documentation with swagger. So if you just go over here and type "docs", check out what we get. Oh, here's your open API
0:57
JSON response. And look, we've got our three things, we've got our API weather, city. If we look at that, it actually shows you it takes a city,
1:06
which is a string. It takes, a query string, and which defaults to metric, and a country which defaults to US,
1:14
and the state, which turns out to be optional. We could even try it and yeah, that looks all good. Execute, the city is required.
1:22
Look at that, Portland, execute. And what is the response? There it is, down there. How cool is that? Right?
1:29
There it is right there. So that's really neat. And if we go back, close this one up. I also wanna have get one for get reports, but check it out.
1:37
You don't have any example Schema. What about this one? does it have an example, schema? It does. super cool. So we'll come back to what
1:45
the example schema the other one could be, but check this out. It knows that this is a thing that we're going to submit. This is the report, submittal.
1:52
Does it know what comes back? No. So we want to fix that real quick. And then Finally, do you really want to document the favicon or the homepage?
2:01
No, that is not part of your stuff. So let's go and address those things. This is easy. We'll just say include in schema is false.
2:10
Now if we just refresh it notice only our API endpoints are there. That's good. But if we go and look at the response value,
2:18
we get no example schema. All that cool stuff about pydantic, it's going to come back and help us. So, like location there and so on.
2:24
Let's go over. None of these are relevant, actually. Let's go over to our API here. What we can do is say on this one,
2:32
what are we actually meant to return? What does this return? It returns a dictionary, and we don't really have a schema for that one.
2:40
So I'm not gonna worry about this one because you can see how it works for all of them. But this one, we know this is a list of report.
2:46
So let's go up here and say the response model is the list of reports, and here the response model is just a report.
2:57
Run this again, see if it works. Seems to like it. Refresh this. So which one are we looking at here? Let's look at the get reports.
3:06
This one. Look at that. It is a list of a full on response. Got the description,
3:13
the location, the ID that gets generated and an example of the datetime there. If we add a report, it says it's going to take one of these.
3:21
And what's it gonna return? It's gonna return the full proper version of it.
3:24
Cool, huh? So we have this really nice built in documentation over here with our FastAPI, and by the fact that we're using pydantic models, or
3:33
composition thereof, right? Reports which derive from submittals which have a location,
3:38
and then we create a list of those, that kind of stuff. That already works really well for what we're doing. I kind of wish it would if it didn't have
3:45
something here, it would look here, but whatever. It's still really nice that it generates that documentation for you.
3:51
Final word is, if you're putting this into production and you don't want it to be a public API, take away the docs. Take away the docs URL.
3:59
There's a way, I believe it's down when you create the app, I don't totally remember off the top of my head.
4:04
But, go over here we set the docks URL to None. When you go back and try this, it's like, yeah, and there's no documentation.
4:12
Right? So when you create the FastAPI app or API, you can just set it to be no documentation or have documentation or even
4:20
better, maybe do it on the development situation, have it but not in production. So there it is, right. This cool little swagger UI for our
4:28
API's, integrating with things like our pydantic models that are already doing the validation
4:33
and the binding. It all comes together beautifully, doesn't it?