I just wish YAML wasn’t so unwieldy for that, especially given the overall complexity of the spec.
I also thing that the tooling hasn’t kept the same pace as it has with graphql, where it’s easy to document your schema and the inspector makes it super easy to play with.
You can write OpenAPI in JSON, which can help a bit with encompassing the complex and frankly fractured ecosystem of OpenAPI.
I have found that the tooling tends to have the problem of not knowing how to catch edge cases like webhooks, websockets, complex auth and additional logic beyond just an HTTP request. Many tools add layers of configuration and extension to work around these, but i feel it misses the mark.
I'm building Borea.dev to solve this pain by keeping the source of truth in your OpenAPI doc and allowing for custom code implementations. We support Python rn, are building out generators for multiple other languages and we're open source :P hope it helps
I also thing that the tooling hasn’t kept the same pace as it has with graphql, where it’s easy to document your schema and the inspector makes it super easy to play with.