RESTful and HTTP APIs in Pyramid Transcripts
Chapter: Documenting your API
Lecture: The documentation HTML and CSS
Login or
purchase this course
to watch this video and the rest of the course contents.
0:01
So we have a little bit of basic documentation working here we don't have really like a nav bar anything like that
0:07
but just pure HTML, we can have that. However, we don't have the actual documentation
0:12
so let's go over here and fill in this piece that we're going to work with now I am just going to paste this in
0:19
because you watching me type documentation can't be the most fun; alright, so what we're going to do is we are going to come down here
0:24
and we haven't got our css yet, but we'll get there and we're going to have a place that talks about all the autos
0:30
here's a little description, here's that get remember that was green like dark green on light green to indicate a get request
0:36
and orange for a put and red would be for delete and so on, we even have a cool little try it button here,
0:41
so you click the button, we're using bootstrap so it gets us button style and you click try it and it'll just go and download this,
0:48
now, I don't think this is actually going to work here because we've added the requirement that you have to log in
0:55
you have to pass the api key, but at least we can see it tell us hey no api key for you.
1:01
Here's the response formats, and notice we've got a bunch of classes and stuff that we can style and we have our examples here in a pre,
1:08
ok, so if we go back over here and we refresh boom, this already looks pretty good, it could be better like this part obviously could be better
1:17
those were like pulled out in little highlights and whatnot, but decent, maybe I should indent this, there we go, indented, looks a little better,
1:25
so let's go and work on the css, so notice we have already a static/docs css up here, but it just doesn't exist, so let me just copy this one in here
1:36
we can look at it real quick, so this is from before I just said alright look, when you talk about the request use some sort of monospace type thing,
1:44
color the git foregrounded and background so it highlights this way the post that way, obviously do the same for put and delete
1:49
and just generally highlight the code parts and make the fonts a little bigger. So not a huge thing, but that looks a little bit nicer, right
1:58
notice how these popped out now. So we have our little back home, we go back we could check out the post that was not done, we'll do that in a second
2:05
but this one, this one's done, do you want to try it you must specify an authorization header, right then we could set up like a test one or whatever
2:14
but for now, this is totally fine. Okay, so let's just put the HTML in the other one, so just like before, standard HTML here, and let's go back home,
2:26
now paste that in there, so now we've got our little documentation. So that's pretty nice, we're back here, we're checking out our service,
2:34
just hit the url so it would be like auto_service@talkpython.fm from our deployment section you would see this,
2:41
and then you could go look at the individual pieces, right, this is not really a great set of documentation
2:46
because I didn't create a whole fancy website just to talk about documentation,
2:49
you guys totally should have the idea and a little template that you can work with.
2:53
So hosting your documentation on github or on read the docs or something like that is totally fine, but you can see that it's super super easy to do
3:00
if for some reason you want to host it inside the same app that serves up the api itself.