[smackeyacky]

The real advantage of sticking to something like Postman for me is that it's easier to share with other people. You can offer somebody a Swagger definition and get blank stares and shrugs, but everybody seems to have access to Postman. Like it's become a de-facto standard for sharing your working API calls rather than a hit-and-miss standard that may or may not actually work compared to the actual system.

[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.