Adam dives into how to document your application using OpenAPI (formerly Swagger) and then how to generate great documentation for your API's using Redoc. He gives us the history of Redoc, breaks down the process for building API documentation, and understanding the OpenAPI specification.

Panelists

Guest

Sponsors

Links

Picks

Special Guest: Adam Altman.

Hey folks, I'm a super busy guy and you probably are too. You probably have a lot going on with kids going back to school, maybe some new projects at work. You've got open source stuff you're doing or a blog or a podcast or who knows what else, right? But you've got stuff going on and if you've got a lot of stuff going on, it's really hard to do the things that you need to do in order to stay healthy. And one of those things, at least for me, is eating healthy. So when I'm in the middle of a project or I just got off a call with a client or something like that, a lot of times I'm running downstairs, seeing what I can find that's easy to make in a minute or two, and then running back upstairs. And so sometimes that turns out to be popcorn or crackers or something little. Or if not that, then something that at least isn't all that healthy for me to eat. Uh, the other issue I have is that I've been eating keto for my diabetes and it really makes a major difference for me as far as my ability to feel good if I'm eating well versus eating stuff that I shouldn't eat. And so I was looking around to try and find something that would work out for me and I found these Factor meals. Now Factor is great because A, they're healthy. They actually had a keto line that I could get for my stuff and that made a major difference for me because all I had to do was pick it up, put it in the microwave for a couple of minutes and it was done. They're fresh and never frozen. They do send it to you in a cold pack. It's awesome. They also have a gourmet plus option that's cooked by chefs and it's got all the good stuff like broccolini, truffle butter, asparagus, so good. And, uh, you know, you can get lunch, you can get dinner. Uh, they have options that are high calorie, low calorie, um, protein plus meals with 30 grams or more of protein. Anyway, they've got all kinds of options. So you can. Round that out, you can get snacks like apple cinnamon pancakes or butter and cheddar egg bites, potato bacon and egg, breakfast skillet. You know, obviously if I'm eating keto, I don't do all of that stuff. They have smoothies, they have shakes, they have juices. Anyway, they've got all kinds of stuff and it is all healthy and like I said, it's never frozen. So anyway, I ate them, I loved them, tasted great. And like I said, you can get them cooked. It says two minutes on the package. I found that it took it about three minutes for mine to cook, but three minutes is fast and easy and then I can get back to writing code. So if you want to go check out Factor, go check it out at factormeals. Head to factormeals.com slash JSJabber50 and use the code JSJabber50 to get 50% off. That's code JSJabber50 at factormeals.com slash JSJabber50 to get 50% off.

Hey folks, I'm a super busy guy and you probably are too. You probably have a lot going on with kids going back to school, maybe some new projects at work. You've got open source stuff you're doing or a blog or a podcast or who knows what else, right? But you've got stuff going on and if you've got a lot of stuff going on, it's really hard to do the things that you need to do in order to stay healthy. And one of those things, at least for me, is eating healthy. So when I'm in the middle of a project,or I just got off a call with a client or something like that. A lot of times I'm running downstairs, seeing what I can find that's easy to make in a minute or two, and then running back upstairs. And so sometimes that turns out to be popcorn or crackers or something little, or if not that, then something that at least isn't all that healthy for me to eat. Uh, the other issue I have is that I've been eating keto for my diabetes and it really makes a major difference for me as far as my ability to feel good if I'm eating well versus eating stuff that I shouldn't eat. And so, um, I was looking around to try and find something that would work out for me and I found these factor meals. Now factor is great because a, they're healthy. They actually had a keto, uh, line that I could get for my stuff. And that made a major difference for me because all I had to do is pick it up, put it in the microwave for a couple of minutes and it was done. Um, they're fresh and never frozen. They do send it to you in a cold pack, it's awesome. They also have a gourmet plus option that's cooked by chefs and it's got all the good stuff like broccolini, truffle butter, asparagus, so good. And you can get lunch, you can get dinner. They have options that are high calorie, low calorie, protein plus meals with 30 grams or more protein. Anyway, they've got all kinds of options. So you can round that out, you can get snacks like apple cinnamon pancakes or butter and cheddar egg bites, potato bacon and egg, breakfast skillet, you know obviously if I'm eating keto I don't do all of that stuff. They have smoothies, they have shakes, they have juices, anyway they've got all kinds of stuff and it is all healthy and like I said it's never frozen. So anyway I ate them, I loved them, tasted great and like I said you can get them cooked. It says two minutes on the package. I found that it took it about three minutes for mine to cook, but three minutes is fast and easy and then I can get back to writing code. So if you want to go check out Factor, go check it out at factormeals, head to factormeals.com slash JSJabber50 and use the code JSJabber50 to get 50% off. That's code JSJabber50 at factormeals.com slash JSJabber50 to get 50% off.

 

CHARLES MAX_WOOD: Hey everybody and welcome to another episode of JavaScript Jabber. This week on our panel we have Dan Shapir. 

DAN_SHAPPIR: Hey, hey from Tel Aviv where it was kind of winter, but now it's sunny again. 

CHARLES MAX_WOOD: AJ O'Neill. 

AJ_O’NEAL: Yo, yo, yo. Coming at you live from the virtual background of Honey I Shrunk the Kids. 

AIMEE_KNIGHT: It's great.

CHARLES MAX_WOOD: Steve Edwards. 

STEVE_EDWARDS: Hello from newly snowy Portland. 

CHARLES MAX_WOOD: Amy Knight. 

AIMEE_KNIGHT: Hey hey from Nashville. 

CHARLES MAX_WOOD: I'm Charles Max Wood from DevChat.TV and this week we're talking to Adam Altman. Adam, do you want to give us a brief introduction to who you are, why you're important, all that stuff? 

ADAM_ALTMAN: Sure, I am Adam Altman. I live in Austin, Texas. I am actually not important at all, but I've had the good fortune of working on some projects that a lot of people are using. So, and that's why I'm here which is an open API documentation tool. 

CHARLES MAX_WOOD: Nice. 

 

Hey folks, this is Charles Maxwood and I just launched my book, Max Coder's Guide to Finding Your Dream Developer Job. It's up on Amazon. We self-published it. I would love your support. If you wanna go check it out, you can find it there. The Max Coder's Guide to Finding Your Dream Developer Job. Have a good one, Max out. 

 

CHARLES MAX_WOOD: So Redock, documentation, everybody's favorite thing to do, right? 

ADAM_ALTMAN: Yeah. 

CHARLES MAX_WOOD: There's some tie in between like open API and swagger, which we talked about a few episodes ago and documentation. So do you want to kind of connect all the dots for us here? 

ADAM_ALTMAN: Yeah, sure. So open API is the new name of swagger. It was formerly known as swagger and at my other company, Rebilly, we decided to adopt swagger to describe our API. So swagger or open API can be used to describe your API and you can use it throughout the life cycle. So one of those points in the life cycle is using it to generate reference documentation. So when we described our API at Rebilly, we fired up the free API documentation tool, Swagger UI, and we found that the documentation looked terrible. So of course, immediately, I thought that we did something wrong. Like we did not describe our API correctly. We misread the specification and we spent weeks researching and concluded that Swagger UI just didn't have support for some features of the spec, which included nested objects and nearly all of our post and put requests except a JSON body. And the corresponding documentation was rubbish. And this led us down the path to building Redoc, which is a free open-source tool that converts your API definition, open API definition into a nice modern three-panel API reference docs. 

DAN_SHAPPIR: So like Chuck said, we had a show about Swagger and OpenAPI a while back. It was in fact show 409. But could you give us like a brief recap of when you say reading the open API specification, what exactly is being read? 

ADAM_ALTMAN: Yeah, so there's an open API specification and there's a few versions of it. So right now we're on version three and version 3.1 is being drafted. So this is a specification that tells you how you can describe an API. And it's primarily for describing REST APIs. So these are your typical web API, which has some HTTP request, and you make some HTTP request, and you get some response back. So you can define following the specification, which is similar but different from JSON schema. If you're familiar with JSON schema, allows you to describe schema objects. So it's similar. It's an extended subset of, I believe, JSON schema draft 4. But that is changing or should change in version 3.1. In the draft, it was just accepted to extend the JSON schema, the current 2019 September version. So you have a way to describe your schema, your resources, which is, let's say, something that might be in a request body or response body of a typical API request. And then you can describe everything else about that. So you can describe your security schemes, which might include how someone authenticates to the API. Could be like an API key or using OAuth 2. And you can describe if there's parameters, parameters in a URL, parameters in a query string. And you can describe the objects down to quite a lot of detail. What type they are? Is it a string or a number? Is it an integer? Is it required? Or is it an optional parameter? And this is a pretty good practice if you are publishing a REST API to describe it using the OpenAPI schema, because there's a whole set of tools out there that you can use it with. And one of the aspects is for documentation, but it's not the only aspect in the API lifecycle. You can use it for generating SDKs or HTTP wrappers. You can use it for generating test suites. So you can assert that responses to your API requests match what you say they're going to be. They're also used in tools like API gateways. So an API gateway may route an API request to a specific back end or multiple back ends almost all of them can use the open API definition to configure the gateway. 

STEVE_EDWARDS: So you mentioned a few different tools there that you can use. I would assume something like Postman is one of the tools that would integrate with something like this? 

ADAM_ALTMAN: Yes, Postman can. 

DAN_SHAPPIR: Now you mentioned that you describe these APIs. If I'm like a client that can connect to this API, how can I access the description for the API? 

ADAM_ALTMAN: So in Redoc, for example, we put a button at the top of the interface so you can download the definition in JSON or YAML. The spec allows for the definition to be written in either JSON or YAML, and Redoc makes them available in both if you wish to download it, to use it. 

DAN_SHAPPIR: So basically if I have an API, I also would put the specification for that API either as a JSON or YAML behind the known let's say HTTP endpoint and make it accessible that way. Is that, is my understanding correct? 

ADAM_ALTMAN: It is. And in the case of, in Redoc, we publish it. 

DAN_SHAPPIR: So I'm not exactly following you. 

ADAM_ALTMAN: So for example, let's say there's a couple of approaches to writing the API definition. One is kind of a design first approach. So where you're going to write the definition before you write any code. And one advantage of that is that it encourages conversation and discussion amongst your team, which might include proxies for your customers or actual customers. And when you're writing, there's a variety of tools you can use to write this definition in, but you might want to store it the same way that you store your code itself, such as in GitHub, in source control, version control. So if you store it in GitHub, you might then want to make this reput and your API is a public API, you might want to make that repository public. So that anybody can go, any of your clients or team members can go there and contribute or consume it. That's one example of how you might publish your API definition. Another is people might write it at the same time that they're writing the code, and they might use code annotations to do that or after. And so for every entry point to the API, they're adding some code annotations. And then there's some tooling that will take all of those annotations and form them into a properly, hopefully, properly formatted API definition and then publish that. And in that case, yeah, you could publish that behind any HTTP server. 

DAN_SHAPPIR: So that would be what, something like JS doc or something like that? 

ADAM_ALTMAN: It could be. 

DAN_SHAPPIR: Okay, so basically, you're saying one of really three things from my understanding happened. Either I planned ahead, created the specification for my API, again, using OpenAPI, either as a JSON or YAML, that's option one. Option two, as I write or implement the API, I also annotate it and that way, the OpenAPI is kind of generated automatically for me via tooling. Or I guess the third option was that I have a pre-existing API and I retroactively document it using some tooling as well. 

ADAM_ALTMAN: Yes. 

DAN_SHAPPIR: Correct? 

ADAM_ALTMAN: Yes, that's correct. 

DAN_SHAPPIR: OK, I understand. OK, so I have the open API document that describes my APIs. And then I feed it into Redoc, and then exactly what happens. 

ADAM_ALTMAN: Yeah, so then we parse it. And we render it. So we render each operation. So OpenAPI calls like an endpoint, the combination of an endpoint and an HTTP verb, like put, get, post, delete, and operation. So if I wanted to create, for example, a pet, using the pet store example, I might post to the pet's path and I might give that operation an ID called, you know, create, add a pet or create pet. So we take each of those operations from the definition and render them into the left navigation and in the body or the summary in the left navigation. And in the body, we render all of the details. And then in a right panel is where we render the request samples and response samples as well. 

STEVE_EDWARDS: So you're saying that you can send a request to an API and then just document it based on what's returned as compared to having actually defined in a file somewhere? 

ADAM_ALTMAN: Well, no, this is actually defined in a file. So we're taking the file, the definition and rendering the documentation based off of that. 

STEVE_EDWARDS: The one point I want to bring home that I've just from my own head here is, basically the API, you've got to document it somewhere. So if I'm changing code in my backend, and I change something like I add a new field that I'm gonna return to my data because my front end needs it, which is a real case in my world every day. So therefore I need to go in and manually either update my API doc or my annotation or whatever in order for it to show up in this documentation, right? 

ADAM_ALTMAN: Yeah, absolutely. 

STEVE_EDWARDS: Okay. 

ADAM_ALTMAN: You can use the same source though to run assertions against your code. So let's say you had some tests a test suite. If your response diverges from your definition, whatever you've defined, you can fail your test suite and then you'll remember faster that you need to update your definitions to keep them in sync with your backend. 

DAN_SHAPPIR: So I'm actually looking at the site now. I think it's redocly.github.io slash redoc. And I see what you're saying. So I'm looking at the pet store example exactly. So yeah, on the left-hand side, I do see all the various, various HTTP operations that I can perform, the parameters in the center, and then the sample on the right, is it only documentation or can I actually use this API to actually perform the, you know, like create requests and see the responses. Like sort of a play box. 

ADAM_ALTMAN: Yes. Yeah. So we have a feature, but only in our commercial version, which has a try it out. In that case, we're going to go ahead and send the request. And it does require cores on the server side, because the request is coming from the browser. And it's typically coming from a different domain name than the API's domain. 

DAN_SHAPPIR: You might want to implement it as an Electron app to avoid the need for that just, you know, as a sort of a utility. 

ADAM_ALTMAN: Makes sense. 

DAN_SHAPPIR: So you said that other such tools exists, but that Redoc has some advantages. Can you elaborate? 

ADAM_ALTMAN: Yeah. So one of the things I guess where we got lucky is that about maybe 10 years ago, there were different standards or different specifications vying to be the standard for how to describe a REST API. And Swagger now known as OpenAPI, ultimately won. And we had built a tool around OpenAPI, so it was specific to that. One of the things about this spec is that it allows you to use a whole wide variety of descriptions. Most of the tooling does not support all of that variety. And in our repository, which sounds like you have Open, we've got an example of one feature called the discriminator. The discriminator is, I guess, as it sounds, it comes from a pattern where the value of one field or one property determines the structure of the rest of the object. So the value, in this example, the value of the pet type. If it's a dog, it's got a pack size. If it's a cat, it's got a hunting scale property. That's an example of a feature that is really not supported by other documentation.tools. Another example is the interactive nesting. So with support for one of any of those JSON schema descriptions, those are two examples. And the documentation has been through a lot of developer testing from a consumer perspective. So from people who actually how is this going to be laid out in a way that's most easy for them to understand how they can send a request. Because oftentimes people are building APIs and they are assuming that their APIs are going to be consumed. And many times they're not, or they're only consumed by someone within their organization because they absolutely have to, to, to finish their job or task. So, this sort of UX research helped us devise or perfect this layout. I wouldn't say perfect because there's still more to do. 

DAN_SHAPPIR: So I'm playing with the pet example and it's really, really cool and nice. I'm there. It's very readable and very clear. So I really like that. Can you give examples of common use cases of the tool that you're familiar with? 

ADAM_ALTMAN: Anybody who's publishing a REST API. Here's a couple of use cases. So one is actually for your published API reference documentation. There's probably a few thousand companies that have published API reference docs using Redoc. So it's a case where you have some public API that you're hoping someone will consume and integrate into their product. Another use case is for internal documentation. So the coordination of front-end and back-end teams to have sort of built on the fly from the definition and to use that as a point of discussion and interaction within product teams. So it's commonly used in product teams. There's many organizations that use documentation just for that purpose for facilitating communication. It's a lot easier to read the rendered HTML than it is to go and read the JSON or the YAML because a lot of people then fall out of their comfort zone and they don't know the exact semantics of the open API spec and they start looking at the structure instead of the content, the actual substance, and by rendering the docs allows people, including some of the less technical contributors, equally contribute to the product's development. 

DAN_SHAPPIR: Can it work like both ways? So, You know, you said that it's easier to read, but theoretically it means that it's also easier to write. I mean, if I'm reviewing the API via Redoc and I don't like something or I want something changed, or I have a suggestion for a change, then can I do that via the Redoc UI? Or do I then, if I want to implement a change, I actually do need to go into the JSON or the YAML?

ADAM_ALTMAN: Right at this point you need to go into the JSON or the YAML or some other, some other authoring tool. We're working on a, on a project. Actually it's, it's, it's in a third version. It's the create open API repo. There's a couple of challenges. One challenge is there's a property called description, which is used commonly to describe any property. So I have a property in my API request ID. I have a property you know, pet type, I have a property, et cetera. And each of those can have a description and the description can accept markdown. So we know if we put markdown into a JSON, it becomes hard to read. And then if we put, try to view it as like a get a diff for the purpose of like a pull request review or something like that, then it's also hard to read or know what's happening. So Redoc, enables a rendered view of that. But another problem is that a lot of people have their API definitions in one file, and those become unmanageable really quickly because the specification has a fair amount of boilerplate. If you're going to have an almost a tiny API, you're already probably at 100 lines of pretty print JSON or YAML. And it's very easy to get to 10,000 lines of JSON or YAML with describing, you know, maybe 30 to a hundred endpoints. And if you're using YAML, which YAML is kind of a better format for the handwritten sort of design and advance approach because of the, in particular, because of the, the way that you can write your markdown and break it into multiple lines fairly easily. It becomes daunting to people because you don't know, well, gosh, which level of indentation am I, when you're in line 7,000 out of 17,000, you become very uncertain of how and where exactly you're gonna add something and not break something. So we devised this repository, we call it create open API repo, which allows you to structure your definition into multiple files. So the specification itself, supports multiple files. But unfortunately, as it turns out, a lot of the tooling out there does not. So you kind of need to do two things. You need to support multiple files. And to do that, we have some organization where you can break your schema into folders. You can break your paths into a separate folder. And that allows you to organize it. And each schema can be its own file. So when you want to go edit the cat or the dog, It's a lot easier to do that because you just need to find the file named cat or dog and go out there, go in there and you're editing a 10 or 20 line file instead of a 10,000 line file. But you also need a tool to bundle all of that together because other tools might be expecting your definition in a single file bundled format as we use the term. So we have a tool also that's called OpenAPI CLI which can validate the definition and bundle it. 

 

One of my favorite communities in programming these days is the Angular community. Every time I go to an Angular conference or meet up with some of my friends who are in the Angular community, I have a great time. And a lot of them have wound up on Adventures in Angular. So if you're doing front-end development, you're looking for a way to keep current on the Angular ecosystem, and you want to have a good time listening to fun people talk about great topics related to Angular, then go check out Adventures in Angular at adventures in angular.com. 

 

AIMEE_KNIGHT: I have one question that's probably going in a slightly new direction, but kind of just talks about potentially some of the different features y'all have. One thing that I thought was kind of handy that I've seen in documentation before is basically just a way to run like a sanity check so that as you push them up, even just like integrate them with your own CI like you would like any other project, a way to run tests just on the formatting. So do you have anything like that available? 

ADAM_ALTMAN: Well, so we do validation of the API definition to make sure it's valid. So we have this free open-source tool called OpenAPI CLI. And a bit different from other projects out there in that it's intended to work with the multi-file format. And there's no need to bundle the file before doing the validation. A lot of the tools out there kind of work the reverse way. They have to bundle first, and then they do the validation. And the problem with that is if the bundling doesn't work. So the modeling doesn't work. You end up stuck and get some mystery error message. And you're kind of stuck in kind of a bad place. Where we're kind of looking to take this, though, is this tool is really inspired by ESLint. And we're focused on the performance of it to make it really lightning fast. And we think that then we can build what we do have a sample to build and release a VS code extension so that you can just be writing or editing your file and get instant feedback from within your IDE of if you made a mistake or not in terms of, you know, with your API definition. 

DAN_SHAPPIR: Going back to what you said before, it does seem to me based on what you're saying that it would be really cool if you created like a similar mechanism to what you have now for viewing the API, a visual tool for annotating and editing the API. Is that something that you're thinking about? 

ADAM_ALTMAN: Thinking about it, yes. I don't think it's in the short-term roadmap, because it seems like it would be quite challenging to get it to the place where we think it would need to be to make a significant impact.

CHARLES MAX_WOOD: One thing that I'm looking at with this is just, you know, you're talking about in order to update the documentation, you have to update that YAML file or the JSON file and I hate writing documentation. The only thing that's worse than that is maintaining documentation. 

STEVE_EDWARDS: And so the I'll developers like documentation. 

DAN_SHAPPIR: Code comments for the win. 

CHARLES MAX_WOOD: I'm against self harm personally. So, but yeah, anyway, it's, it's an interesting conversation to have, but. Yeah. When I update the API. I mean, how do you ensure that people are going to go update the docs? I mean, that's, that's the other thing. You can make those assertions and force them to, if their CI is going to complain about it. But unless you're doing something like that, where there's some kind of monitoring on it, you have a people process for keeping this stuff up to date. 

ADAM_ALTMAN: Yeah. I think different companies have different processes. So like in a design first organization, you're going to go make a change to the API. You're going to start with the pull request that makes a change to the API definition. That isn't going to be merged, but it's going to be, say, reviewed and approved. Once that's approved, then you're going to go ahead and implement those changes in the backend. That's an example of a people process. Others might also be consuming the definition within their apps themselves. If you're actually using and consuming the definition, there's no doubt that you're going to make sure that it's up to date. It may be your front-end app that consumes the definition. It might be your back-end app. In either case, if you are using the definition for some purpose, here's an example of a purpose from real life. In Rebilly, there's a few key resources like customers, and customers have certain properties. Sometimes those properties change, and those properties can be filtered and segmented and the front-end app relies on the definition to grab what properties are available to display. And it just displays them or makes them available. Like in the corner of a grid, you can click on a button to show or hide columns on a data table. And that's one example of how it's used. Another is in forms. So a form might have a select menu or radio button option. And in Rebilly, we're using the definition to see if a field is defined and it's a type as a string, and it's an enum. You can define a field using the spec as an enum, and it has a limited number of values, say, I think five or less. We might display it automatically as a radio button. And if it's a six or maybe it's four or less, if it's five or more, then we're displaying it as a select menu. And so those are examples of how you might use the definition within your app itself. And if you're doing that, then without a doubt, you will make sure that your definition is up to date. It grabs the latest, like Rebilly's app at build time grabs the, it's pinned to specific version of the definition, but it grabs whatever version it's pinned to and as part of the build, it's build script. 

DAN_SHAPPIR: I also think just a key aspect here of Redoc, and correct me if I'm wrong, is that since you direct it to a URL with the specification of the OpenAPI specification, that documentation is essentially generated on the fly from that OpenAPI specification. So the documentation is always up to date as long as the documentation that I'm pointing at is up to date. Okay, so that's obviously a really big benefit. The fact that I'm not generating documentation and then storing it somewhere, and I need to make sure that I have a process that generates a new version of the documentation every time I update the API. Soon as I update the API, I always assuming it's behind the same URL, the documentation will also be, like by definition, up to date as well. 

ADAM_ALTMAN: Exactly. And there's different options for that too. So we've got a way that you can just, we call it our JS CDN, where you just include your documentation or your API definition URL on a page with wrap it in a tag and add a include our script and it will load the documentation. Then there's other tool we have Redox CLI, which sort of pre-renders the documentation and that you do need to trigger. So you need to integrate that, for example, into your CI. So whenever you change the documentation, you publish some change, it will build that, the pre-rendered version of it, do that. And then we have a commercial product, which has a workflows aspect, which integrates into products like GitHub, where we can build a production version of your docs and unlimited preview versions. So if you have different PRs open, to make changes to your API, we also can build a preview version at a different URL and those can also be access-controlled. So if you want, you can access control that too. 

DAN_SHAPPIR: So since you ran through quite a number of both open source slash free tools and actual commercial tools, you mentioned quite a number. Can you do like a quick rundown, like a list of all the ones that, you know, of both kinds that you have? 

ADAM_ALTMAN: Yeah, sure. So, Redoc is our original open-source product. Then we've got create open API repo. This is a repository which is a little tool for creating an opinionated multi-file structure for your open API definition. Then we've also got open API CLI, and that is a tool for validating and bundling your API definition. Part of Redox, it also has a Redox CLI option. So the Redox CLI option is for bundling your docs into pre-rendered HTML files. So those are all free products. And then if we move over to the commercial or paid products, we've got a workflows product, which is like a CI CD, which is going to validate your API definition, add it to the registry, and can kick off things to build your reference docs or build a contextual documentation portal. We also have a super-powered version of Redoc, which we just call Redocly API Reference. That is a commercial version. It's very similar to Redoc, almost same usage. There's more theme controls. We've got a different router, so it's got more performance ability for people targeting people who have really large definitions where it's too slow to render all of the entire API documentation into the page at one run. And it's got other features like the try it feature where you can send API requests and try it out and a couple other bells and whistles like that. You can do some more nested organization of your left navigation but it's really targeted for people who are looking for a target or to build like large enterprise docs or have some very specific needs. 

DAN_SHAPPIR: And where do I find all these tools? 

ADAM_ALTMAN: So you can find these tools at redoc.ly. That's our website. And you can find me on the Twittersphere. I am Adam Altman at Adam Altman. And you can find us at Redocly and you can find us on GitHub as well. Our organization is Redocly and you can see all of our open source packages published there. 

CHARLES MAX_WOOD: Awesome. 

 

Over the last many years we've had a ton of terrific people on JavaScript Jammer and one thing that I realized over the last few years was that we were missing out on some of the real story there. So we would talk about the topic that they were experts in and help you keep up on what's going on in the JavaScript community but I felt like we had these terrific people on there and we didn't really talk about who they were. So I pulled together a show called My JavaScript Story. And what we do is we interview the people that we've had on JavaScript Jabber or people just from the community. Maybe we'll have you on sometime. And we talk about how they got into programming, how they got into JavaScript, what they're working on, what they're well known for and how they've developed their career. And some of the people are extremely well known and come from really interesting backgrounds. So if you're curious about how your JavaScript heroes got into JavaScript, then go check out my JavaScript story. You can find it at my JS story.com. 

 

CHARLES MAX_WOOD: All right. Well, let's get some picks. AJ, do you want to start us off with picks? 

AJ_O’NEAL: Let's see. Hmm. What can I pick? Okay. So nerdy. Well, whenever I never picked something that's not nerdy, that that's not even how I roll. I found out that lots of people all over the world use a site called play Asia to purchase games that are not released in the United States. And for those of you that are Nintendo fans, which should be everyone who has a brain and likes fun, which should be everyone who has a brain, and for those who are fans of Final Fantasy VII and VIII, there is a physical copy that is available, that is in English, that is region free that can only be bought from Asian stores. So you can go to Play Asia and you can buy your Final Fantasy physical copy. Now, warning, it's basically just the PlayStation discs ripped, put on an SD card with an emulator on the card and a couple of localization things changed for like A button versus X button. And a couple of the assets are replaced with higher pixel density assets, but it's a pretty crappy experience, pretty much like playing on the original PlayStation with just a tiny, tiny bit of enhancement. So be warned about that, but I was pretty excited about it. So I picked play Asia. 

CHARLES MAX_WOOD: Nice. How about you, Dan? 

DAN_SHAPPIR: Okay. Then so for a while I've been picking like a whole bunch of less known, but from my perspective, really good fantasy books and series of books and I've kind of stopped for a while, so I'm back to that. So this time I want to mention a series of books called The Old Kingdom, or Old Kingdom actually, not The Old Kingdom, or maybe it is The Old Kingdom. Anyway, it's by Garth Nix, who's an Australian fantasy author. It's supposedly like for the teen audience, but it's actually, from my perspective, it's a bit dark for that. So it's a really good read, I enjoyed it. So I read the first three books. It's like a series, but really each book kind of stands on its own, especially the first one. So if you just read the first one, you'll enjoy it a lot and you don't even need to continue. And from my perspective, it's actually also the best one. And now that I'm actually looking at it on GitHub, I see that he sends his published two additional books. So that would be interesting for me to check them out. I really enjoyed it. First of all, one of the benefits is it actually has a heroine which is kind of unfortunately uncommon in this type of books. And she's a very interesting personality. So that's a benefit. Also, she has pets or actually various heroes in the books have pets, which is also kind of uncommon in some of this literature. Like I said, it's a bit dark, but it's highly enjoyable for my, I really liked it. The stories flow really well and it's highly recommended and I'll share the link. So that's my pick. 

CHARLES MAX_WOOD: Nice. I'm always looking for new, good fantasy-type series. So good stuff. Amy, do you have some picks for us? 

AIMEE_KNIGHT: I do. I have a list. I have a bunch of different YouTube channels for different like developer, well, just different dev stuff. And then the cool thing is they actually have listed out on this GitHub repo like a lot of different languages. So if you don't speak English, you might learn better from one of these other teachers. So it's a super comprehensive list. And, you know, I traditionally get this kind of information off Twitter and podcasts, but YouTube videos are probably pretty awesome too. So that's gonna be my pick for this week. 

CHARLES MAX_WOOD: Nice. Steve, do you have some picks? 

STEVE_EDWARDS: Yeah, so I've been working on, I guess, getting my skills a little more well-rounded in the web development sphere. And so, I've been working a lot on actually being able to put together a template, a design for my own site. And so I actually have come into the modern world and started looking at CSS Grid and CSS Flexbox. And Grid just blew my mind with how easy it is to use to lay out a site. And the way I learned it is with a couple of free courses from WestBoss, from the Syntax and he's got him on his site, westboss.com. The grid course, I guess, was sponsored by Firefox. And so that's why it's free for everybody else. But in both those courses, he does a really good job of just walking through all the intricacies of Flexbox and Grid and lots of examples that you can use to play with some projects at the end that do a pretty good job. And I was able to take what I learned from there and put together a template on my own that I copied from another one that I had bought

 

had jQuery and Bootstrap and stuff, and I made it the same design in a heck of a lot less code and a heck of a lot less JavaScript just using CSS Grid. 

DAN_SHAPPIR: Yeah, CSS Grid is really awesome. We've also switched to it at Wix, and it's enabled us to get rid of a ton of JavaScript code that we use for fancy layouting. Now we just need Houdini to happen everywhere, and the whole world will be hunky-dory. 

AIMEE_KNIGHT: Yes.

CHARLES MAX_WOOD: Yeah. CSS is one of those things I want to learn more about. 

STEVE_EDWARDS: But yeah, I used to, you know, it's been a long time since I've really delved into, you know, designing and laying out. And I had nightmares of, you know, clear fixes and floats and, and all that stuff. And once I got into grid, I was like, wow, so much easier. And it reminds me a lot of just HTML tables in some of the, the methodologies and you know, the way things work ordering reminds me of weights in Drupal for anybody who's ever done Drupal, you know, how you can make things higher or lower and in a list type thing. So there's some familiarity in some cases, it seems to be, you know, like I said, HTML table stuff just renamed or used a little differently. So, and then there's a lot of new stuff too, but yeah, it's really amazing how easy it is. 

DAN_SHAPPIR: I'm old enough to remember actually layouting my HTML using tables. 

STEVE_EDWARDS: Oh my gosh. I can remember some of my first websites I used did. I can remember literally going online and well how do I lay this out and people said oh use HTML tables to do this because you can do this and this and that's what I did. And then all of a sudden that was bad and you don't do that anymore and now we're back to CSS grid. 

DAN_SHAPPIR: Yeah you've you've never really done HTML until you've put a table in a table in a table in a table. 

STEVE_EDWARDS: That's good tables man. I can still remember that side I did that on too.

AJ_O’NEAL: Amazon must be so upset because I'm pretty sure they just changed like three months ago from tables to non-tables. 

CHARLES MAX_WOOD: So, yeah, you splint at the layout and try and figure out what the call span is supposed to be, right?

STEVE_EDWARDS: Exactly. Call span, row span. Yeah. Now it's just called span and CSS grid, but. 

CHARLES MAX_WOOD: Good deal. I'm going to throw in some picks and then we'll have Adam share with us. I don't know if I shared this last week. I've been listening to a book series that I listened to probably 20 years ago or more. It's by Raymond Feist. It was picked on the views on view podcast. It's the magician apprentice, magician master, rift war saga books. I have really been enjoying them. I didn't remember anything from the plot. So it was kind of like listening to them on audible for the first time. I'm still really, really enjoying them. So I'm going to pick those. So definitely check those out. And I've also been watching, and I don't know if I picked this on the show before is a man in the high castle. It's an Amazon Prime original series. I guess they're finishing up after four seasons and the seasons are like 10 episodes. So it feels like I'm watching one of the like Doctor Who or something from Britain, you know, cause like, Oh, there are eight episodes. And, but yeah, really enjoying that. So if you're kind of into the historical fictional anyway, so, uh, the, the premises is it takes place in a world where the United States and the allies lost World War Two. Like they get films from alternate timelines. And so it's, it's kind of interesting to see how, you know, somebody seeing a film of the allies winning the war affects them in a world where the allies didn't and stuff like that. So anyway, I'm, I'm really enjoying the show. I'm about halfway through the second season. Yeah. I kind of get an episode here and an episode there cause I don't watch a ton of TV, but this one's really kind of got my interest. I'm also excited to watch the next season of The Expanse, which started on sci-fi and then Amazon prime picked it up. And so they did the last season and they've done the current season, but I haven't watched any of that yet. I have listened to all the books on audible and they're terrific too. So if you're looking for some, uh, divertment, check that out. Uh, Adam, 

STEVE_EDWARDS: friends that were, uh, I was talking to this weekend about the man in the high castle and they said actually the show was better than the books. So I, I assume that's subjective.

CHARLES MAX_WOOD: I have not read the book, so I don't know. 

STEVE_EDWARDS: Yeah. That's what I've heard about. 

CHARLES MAX_WOOD: Yeah. I'm kind of tempted to just watch the rest of the show and then read the books. So we'll see. 

ADAM_ALTMAN: I will second the expanse. It's excellent. 

CHARLES MAX_WOOD: Yeah. The series and the books are both terrific. 

ADAM_ALTMAN: Yeah. I haven't had exposure to the books, but the series is fantastic. I'm binge watching it. I've also got a couple other things. I've got concepts app. So Concepts app is a flexible sketching tool. I literally bought an iPad Pro so that I could use this tool. You just sketch, you have this infinite pad that you can contract or zoom in and move it around and all these different pens to use or pencils, different things. And it's just, I'm not an artist by any measure, even at the kindergarten level. I just find this so helpful in work and in doing anything, just starting with almost going back to paper and pencil in a way, but I've got this kind of endless canvas that I use. So that's been fantastic. My other pick is a new book, just got this week, A Leadership Strategy and tactics by Jaco Willink. And so I help lead a team and I find this book has some valuable lessons and tips. So those are my picks. 

CHARLES MAX_WOOD: Yeah. Jocko's book, Extreme Ownership. I really loved that book. 

ADAM_ALTMAN: So yeah, it's great. Great book. That one's great. This one, this one's really good. Just saw him. He just, he's on a speaking tour, uh, promoting this book and gave it really a powerful moving performance the other night here in Austin. So 

CHARLES MAX_WOOD: now I'm jealous. All right, good deal. Well, thank you for coming, Adam, and talking to us about, you know, some of these tools that we can use to document our APIs. We'll go ahead and wrap this up. Thanks to our panel as well. And until next week, Max out. 

AIMEE_KNIGHT: Bye. 

ADAM_ALTMAN: Bye, thank you. 

 Bandwidth for this segment is provided by Cashfly, the world's fastest CDN. Deliver your content fast with Cashfly. Visit c-a-c-h-e-f-l-y.com to learn more.