[Improvotter]

I've used them all: Postman, Insomnia, Paw, and other online web apps. Unfortunately none come close to being usable for large APIs imo. Some of the problems I faced off the top of my head (it's almost 2 years ago now since I tried them all though, but I haven't seen much change to be honest):

Insomnia: doesn't really have any support for documentation stuff. It is just an HTTP client that if you share your workspace with your team, is some kind of documentation. But you cannot share this outside of your organisation.

Postman: their documentation implementation seems one of the better ones, but Postman itself just isn't very DRY. For example we have a slightly different authentication scheme which isn't supported so we had to add a simple Javascript snippet to each request, but keeping all of them updated is impossible. I personally also wasn't a big fan of their client and it's not very user-friendly imo.

Paw: honestly pretty good. I asked them a few years ago to implement this and keep me posted. They eventually implemented some documentation stuff, but it's proprietary and using a plugin to convert to RAML or something else is a pain. When I used it, it also wasn't very expansive. It also faces the same problem as Insomnia: you are not able to share it outside your team. Though it also requires everyone to buy Paw and own a Mac. I switched to Linux a few years ago and so don't use my account anymore, that I paid for.

OpenAPI/Swagger: OpenAPI itself is great, but the website GUI that Swagger converts it to is basically useless for large APIs. You cannot nest anything and it is not very good for public documentation.

RAML: I personally love this syntax the most. Though there barely is any support for it. You cannot find any mature library or application that can convert it to actual usable documentation pages. It's also honestly a big pain to write all of the documentation at once.

BlueprintAPI: this is just way too barebones. I immediately stopped using it after trying it.

There were some others I tried, none really noteworthy. It's been a while as well so it's possible that some of my opinions are out of date.

[asdkhadsj]

It's always surprising to me that something so central, api documentation, is so abandoned in the industry. It's.. weird.

I guess it shows how little devs prioritize documentation.

[TuringNYC]

Not sure about open source projects, but in corporate settings it is often driven by short term thinking in priorities, sometimes driven by short term incentives that reward features over usability/support.

[xtiansimon]

With products like Swagger, I find the term ‘documentation’ a misnomer. Oh-well.

[Chris2048]

I like the fact insomnia has no extended support for documentation, I want it to only be a simple http tool.

I use swagger for endpoint documentation. ideally, I could just post an example from swagger into insomnia, or import basic examples.

What do you mean by "You cannot nest anything" wrt swagger?