[Jonathanks]

I used OpenAPI exclusively on my previous job. But it was only me, the back-end developer. My colleagues appreciated the documentation. But when it was time for me to leave, the team moved to Postman. OpenAPI was another DSL to learn, and they didn't consider it worthwhile. Although there are WYSIWYG editors for OpenAPI, they are not as popular as Postman. There's just a lot of inertia in the way of OpenAPI adoption.

Even though I like it, I find the DSL too verbose. A slimmer DSL would be great. Generating the spec from existing code worked sometimes, but it coupled the API design process to the implementation code. I'm not a fan of that.

I think OpenAPI's appeal is in tooling: provide a spec, then you get documentation, API consoles, mock servers, etc. for free. If it's for documentation only, people will continue using Postman. Postman already provides mock servers and consoles, so there you have it. It'll take more tools built on OpenAPI to make it very appealing.

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