Yes, the tooling around OpenAPI spec is not great. However we've worked around it. We write most of our spec by hand. We thought it would be horrible but it's

Yes, the tooling around OpenAPI spec is not great. However we've worked around it. We write most of our spec by hand. We thought it would be horrible but it's not. All our APIs accept and respond with JSON so the OpenAPI payloads are pretty much JSON schemas which means we can parse and load them up in our functional tests and automate the schema validation as part of a functional test suite. We catch a lot of unintended changes to API contract with this approach (customer is now customer_id because serializer decided so and stuff like that).