Modern APIs with FastAPI and Python Transcripts
Chapter: Accepting inbound data
Lecture: Automatic documentation with FastAPI and Swagger/OpenAPI
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?