Like several people here (the localhost $ref threads especially), we hit problems generating a client from the official Swagger 2.0 spec. We ended up with hundreds of lines of repair code fixing recurring classes of defect.
Patching the spec forever wasn’t sustainable, so we took a different approach: we now maintain a corrected OpenAPI 3.1 document for the Public Data API, built from the Developer Hub documentation and cross-checked against the API’s actual behaviour. 34 endpoints. To keep it honest, a full integration suite runs against the live API daily and on every change, so if the API changes shape we find out the same morning.
Everything is MIT licensed and open-source on Github:
- The docs: companies-house.jxd.dev
- Github:
jamiedavenport/companies-house - A TypeScript client generated from it:
@jxdltd/companies-houseon npm
If you’re generating clients in other languages, the spec should work with standard OpenAPI tooling; that was the point.