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