Automating Empathy: Test Your Docs with Swagger and Apivore
summary
Claim: API docs become executable tests that force code to match description. Workflow uses Swagger/OpenAPI for machine readable docs and Apivore to run spec checks, producing failing tests, then implementing just enough code. Pilot takes 29 days and 18 PRs, adds ~1800 lines and deletes ~2700, uncovers mis-scoped permissions, incorrect status codes, stray timestamps and unused endpoints, and yields a doc-first process that turns documentation mismatches into concrete bugs to fix.
AI-written summary · about
chapters (12)
- 0:00Introduction
- 0:55Documentation
- 3:00Usage Documentation
- 5:52Human Error
- 9:18Guilt
- 11:22Documentation Driven Development
- 17:06Swagger
- 19:22API Organization
- 31:37Errors
- 33:05caveats
- 33:59convincing your manager
- 35:53fixing the API
related talks
38mZen And The Art Of Automanually Creating API Documentation - An Inquiry Into Process
30mRswag: Automated API Documentation
59mHandy Tools for Designing Great Web APIs
39mAPI Development in 2017
20mOpenAPIspec
45mFuzz Testing Web APIs: Overview of Existing Tools
23mDesigning APIs Both Humans and AI Love
44mSeamless Upgrades: Mastering API Compatibility