Btw, thought of something else. With OpenAPI you can actually embed examples in the spec. I believe there are tools to generate postman requests from these also.
I agree with you. With OpenAPI you can be more specific about what your API does. You can add examples and refer to the output of an API call (useful if you need to point out relationships).
When I have time, I may work on more tooling for OpenAPI. I'm thinking of a way of specifying workflows by connecting APIs in a specification, then deriving tests for that workflow. A way of saying, "always call this operation first, then use the response to call this other operation." Then the tool can test entire workflows automatically.
