Why isnt everyone using Swagger/OpenAPI?

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.

It is verbose, You often need to define type twice in Open API definition and in Java/Typescript. In addition, swagger UI is not very good. Tooling like editor support, testing, benchmarking is lacking compared to even Postman.

In most cases, there is plenty of good alternatives:

  - Sharing types
  - API/SDK client libraries
  - GraphQL
  - gRPC
  - hasura/postgrest
  - Postman

The only good use case for Swagger/OpenAPI is when you need to expose API to third parties, but even then the above solutions can also be applied.

Personally, I find it very cumbersome. Just look at the very first example they show on their website (https://swagger.io/docs/specification/basic-structure/): it’s not pleasant to work with.

From my experience Swagger tends to produce not so great stuff whenever a bit out of the ordinary solutions are required.

It does work ok imho, but far from being for everyone.

we wanted to, but it's quite steep of a learning curve to create and consume according to spec.