We tried writing OpenAPI docs to implement a contract-first development workflow, with the idea that backend & frontend/mobile engineers would agree on the API interface by discussing OpenAPI changes in a pull request, and only then start implementing it (on the backend side) and using it (on the client side).

This didn't pan out well, because it turns out OpenAPI isn't very easy to read, especially when you're reviewing a diff in a pull request. We didn't get the engagement we were looking for in pull requests.

We've since invested in building a simpler, human-friendly API description language based on TypeScript, which exports to OpenAPI 3. It's still early, but we've got a lot of positive feedback and quick adoption across the company (50 engineers).

You can check it out at https://github.com/airtasker/spot. Feel free to send us feedback in GitHub issues or replying to this comment :)