Building an Accessible API Spec with Traditional Engineering Teams
summary
Argues for a reusable OpenAPI-driven modular spec using $ref to stop repeating schemas, recommends OAuth2 and simple API key flows plus a tiny validate api endpoint that returns “it works”, email and minutes used, and shows increased onboarding success. Suggests using ReadMe/Redocly for human docs, automated tests and product-style user stories to chip away at technical debt, and dogfooding via a Box integration that runs the media-enhancement API as a no‑code proof that the spec and product actually work.
AI-written summary · about
chapters (14)
- 0:00Intro
- 1:25Who am I
- 2:32Common issues
- 4:38Modular spec
- 6:29Authentication tools
- 8:09Simple wins
- 8:40User expectations
- 11:39Documentation Platforms
- 13:01Technical Debt
- 14:09Agile Mindset
- 15:23Use Your API
- 17:27Enhanced API
- 18:22Communication
- 19:12Conclusion
related talks
22mBeyond the Spec: Making OpenAPI More Human
35mDocumenting APIs: new era, same craft
21mLet there be docs!
27mBuilding Great Web APIs
35mOpenAPI for Documentarians
38mThe Secret to Brewing up a Good API
47mContract-Driven API Development with OpenAPI Specification
38mZen And The Art Of Automanually Creating API Documentation - An Inquiry Into Process