How We Unified API Tests, SDKs, and Docs into One Workflow (docspring.com)

DocSpring unified its API tests, SDKs, and docs into a single automated workflow so every client library, example, and OpenAPI schema come from one tested source of truth. After struggling with brittle custom OpenAPI Generator extensions and asynchronous PDF generation (webhooks vs polling), the team built a Go-based synchronous API proxy (sync.api.docspring.com and sync.api-eu.docspring.com) that handles waiting, retries and returns a download_url for single long-lived requests (with ?wait=false for async). That let them simplify client libraries and delete fragile generator hacks. The real innovation is the test-driven pipeline: 300 RSwag examples (covering 40 operations) are run as Rails request specs to generate the OpenAPI schema, then OpenAPI Generator produces SDKs in nine languages, and the same RSwag harness runs those tests against the generated clients — totaling 2,700 end-to-end checks. This caught real issues (e.g., numeric pagination typed as floats, broken file uploads requiring a Ruby HTTP lib patch) and proved why generated SDKs still need testing. The work also shipped a new Starlight-based docs site and API reference. AI coding tools accelerated the final integration, and the team plans to consider open-sourcing the framework for others.