No matter how big or small your API, no matter the audience, internal or external, you need to provide clear and precise documentation so that others know how to use it. Since its inception as Swagger almost ten years ago, OpenAPI has been steadily gaining ground as the de facto specification for describing REST APIs. Whether your API is yet to be built or has been around for a decade, OpenAPI is a tool you can use to document all the parts of your APIs.

In this talk, I’ll introduce you to the basic concepts of OpenAPI, we’ll use it to create documentation for a simple API, and I’ll leave you with a few tips, tricks, and gotchas I’ve learned along the way. You should be able to take what you’ve learned and immediately begin describing your APIs with OpenAPI.


Comments are closed.

Ian Littman at 15:26 on 24 Oct 2019

Into-level material and has a few technical glitches, but strong presentation nonetheless, and pulling in audience participation helped with the infamous afternoon slot slump.

One nitpick: using Paw is a bit limiting audience-wise, even though it's a solid tool, both due to its Mac-only limitation and lack of a presentation mode. I believe Stoplight has some web-based tools that would work similarly without those limitations. Or Postman, but I'm guessing Stoplight would be a better fit due to their tighter API focus.

Dana Luther at 16:40 on 24 Oct 2019

I’ve heard a ton about OpenAPI but hadn’t really had a chance to dig into it. This was a fantastic introduction.

I would really like to learn more about the middleware portion because I feel like that’s where it really comes to life? (Maybe trade off some of the live demo for a little more middle?)

Wonderful grace under pressure with the live demo though, working or not you handled that well.

Nathan Pelton at 22:45 on 24 Oct 2019

The tools that you showed look very very useful in setting up and configuring an API. I saw some swagger files on a project that I was working on but didn't understand what was going on. Now it makes a lot more sense.

Sean Prunka at 11:35 on 28 Oct 2019

I'm looking forward to trying to apply these tools to our existing APIs and hopefully guiding them toward a more RESTful state.