RESTful and HTTP APIs in Pyramid Transcripts
Chapter: Documenting your API
Lecture: Adding the documentation views
0:02 All right, so what we're going to do in this example is
0:04 we're going to add some extra pages, some extra views to this website
0:08 and those can function as documentation, in our case things are really simple,
0:12 we just have a few calls, a few end points
0:14 and we've decided bundling them together on to our little service here
0:18 is better than having some other place to maintain,
0:20 that might not be the best for you,
0:22 but for what we're going to do, that's how it's going to work.
0:24 So what we want to do is we want to come over here
0:26 and notice we have our home page renderer here
0:28 and our view and let's add one just called docs,
0:31 and we have something really similar, so I'll copy this across like so
0:35 and for some reason our system hasn't found pyramid yet
0:39 we just got to restart PyCharm, it'll be fine;
0:43 so here we have our view config all set up and this is going to be docs
0:47 and let's say all autos, and then every one of these is going to be a get request
0:54 but some of them are going to describe get,
0:56 some of them are describe put, and so on,
0:59 so we'll call this get something to that effect.
1:02 Now this template slash my template, not so amazing
1:05 let's go over here and make this a little bit nicer.
1:07 So let's try to organize this, we will create a directory here
1:10 let's create one to hold our existing thing, I'll say home,
1:12 let's create one for all the docs templates
1:17 and then let's create one for things that are shared across them
1:22 so for example layout goes into shared, that's great
1:25 and my template is going to go into home, let's do that
1:28 and let's also rename this to index or home or something like that.
1:33 All right, so if we look, I made a copy here so it kind of duplicated that,
1:36 but let's look at this one, notice how it's sort of refactored
1:43 it took a really good shot at it and renamed that part
1:45 but it didn't catch the home here, ok, so that's good
1:48 let's just make sure this still works, we better go ahead and add that
1:53 I did want to assess this part, we'll come back to this,
1:56 okay so now we want to come over here and we want to say /docs/
2:01 and what are we going to call this, we are going to call this something like
2:04 let's go ahead and make the route name and the function name
2:07 and the template name all match, so we don't go crazy
2:10 so let's just call this docs_all_auto_get, maybe it will just be all_autos_get.
2:14 So down here, let's make a copy of that and make it all autos get
2:21 ok so we're using this layout, now with this reorganization
2:25 this doesn't quite line up anymore, so we need a ../shared/ like this
2:29 on all of our little templates, when I say all I mean the two that we're doing,
2:34 all right, so we are going to need to say go up and look in the shared folder
2:37 but this is going to be a much nicer organization
2:39 in this simple site it doesn't really matter, in a real site this gets massive right
2:43 so this organization is super important.
2:45 Okay, so come over here and let's just put
2:48 so we could just have I'll put a little something like this will be something like this
2:53 this will be get/autos and I'm going to put some html here
2:57 it's nicer and we'll talk about in a second right
2:59 but the idea is all we have to do is have one of these pt files
3:01 it points to the shared layout, it has a content section,
3:04 and then we just put straight plain html, you could have a dynamic
3:08 but for documentation, probably not.
3:10 Oh yeah, one more thing, let's go fix that.
3:13 So we come to our main, we go to register routes
3:16 and down here we're going to have another one
3:19 what we're calling it, something like docs_ that
3:25 and it's going to be let's say docs and let's just say all_autos we can add a get
3:31 or just all autos, right, this is how you get all the autos.
3:33 Let's have one more, in there docs post, and this will be create auto,
3:40 so these are the two that we're going to work with.
3:43 Let's just get this first one going, so we run this,
3:46 if we didn't mess anything up it should be working, here we go
3:50 and if we go to /docs/all_autos, boom, there you have it, we're hitting this page
3:57 now the one all autos create auto, that one doesn't exist;
4:01 so let's go ahead and do that really quick as well.
4:04 So we just want to duplicate this, and notice there's really no logic
4:08 we're just saying serve up that template, so this is going to be all autos post
4:12 and so is that, so this all line up great, and let me just put post here
4:20 ok so if we come back to our home page, here
4:24 we have these little links where it says, it sends you off there,
4:27 let's actually send this to the documentation, let's say /docs/all_autos
4:31 let's have the other one, say create car, we'll call it create autos
4:39 and this will be post like that and so on.
4:41 If we run this, we should be able to at least navigate around a little bit now
4:44 so here's our home page, if we click this,
4:46 it takes us to our api get click this it takes to our post.
4:49 Okay, so the overall structure is set up and now all we have to do is
4:53 put the actual contents of the documentation in here and do little style magic.