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