Auto generate Open API documentation

[Falci]

It would be great if we could extract an OpenAPI compatible documentation of endpoints available in hsd.

Such documentation make it easy to automatically generate:

• Clients implementation (no need for hs-client syncs/updates)
• Documentation websites
• Typescript types

[rithvikvibhu]

I'd love to see proper hints in IDE and @Anunayj's comment makes sense.

The first point is much more useful imo. Even after the recent clean-up, hs-client isn't up to date with all API changes in hsd. Having an OpenAPI spec will mean:

• Like @Falci mentioned: always up-to-date hs-client, and good docs to go with it
• Clients/SDKs in all languages with minimal work (common ones like python, low level C / Rust, etc. langs)
• Can import into http clients like postman, etc.

[Anunayj]

Woops so I deleted my comment, I misunderstood what the PR actually was for Here's my original comment:

I tried generating TypeScript definition from the JSDoc. and except for one thing missing the JSDoc definitions everything worked fine. There were a couple problems though, the primary one being that optional arguments aren't clearly marked in JSDoc, in many (most) places. I think that'd be the easiest way to approach Typescript types right now.