[yellow_lead]

The problem is that your API then doesn't have a clear specification. Or maybe it does, but this doesn't communicate it.

Showing some examples can still lead a team to run into an edge case when they find a different behavior for a different value passed in the API body. At least OpenAPI has a way of documenting such behaviors.

[yellow_lead]

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.

[Jonathanks]

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.