Documenting Your APIs (with OpenAPI)

When you're building an API, you often how know you want it to work. You'll hopefully document it somewhere, but the format of that documentation will vary. In this talk, I'll walk you through the reasoning behind a human- and machine-readable format for your API documentation and the tooling that is built around the OpenAPI ecosystem. You'll learn how you can get kickstarted with documenting your existing APIs and create a stronger domain model for interactions with the API. I'll then show different methods to verify that your OpenAPI specifications actually match your implementation of your service, helping you catch a break in contract, with the end goal of being able to drive your API functionality through your contracts, rather than documenting the contract after implementation.

Events that this talk has/will be at:

  • OggCamp on Sunday, Aug 19, 2018 as a talk.