I've been using OpenAPI for quite a while now and I find it quite easy to work with. Sure there were quite a few things that were hard to do in version 2 (a.k.a

I've been using OpenAPI for quite a while now and I find it quite easy to work with. Sure there were quite a few things that were hard to do in version 2 (a.k.a. swagger), but most of them were fixed in version 3. You're right that the libraries and code generators for it are a mixed bag, and really can make a difference between it being easy to work with or difficult, but I'm not convinced that's a good reason to start from scratch. Don't let that stop you trying though, if you come up with something good then I'll be there in 10 years to start using it when it's proven itself :D. The best bits of advice for those looking to use OpenAPI specs with their API are: 1. Make the OpenAPI spec the source of truth - view it as the contract you have with people using your API. 2. If you've got multiple services working with the same data structures then host your JSON Schema separately and reference them in your different OpenAPI specs. 3. Use the versioning in a sensible way, on both your OpenAPI specs and your JSON schema - Semantic versioning works well for me. 4. Make sure your integration tests go through the full routing logic and test your API options (i.e. don't trust the code generators and frameworks). 5. Build your documentation from it - which in turn means that you need to make sure you use the description fields.