Great idea for facilitating writing API docs once there will be a convertor to OpenAPI (or is there already?)

When I clicked on the title I actually thought to find the limitation of OpenAPI, namely, it's inability to capture dynamic APIs (and GraphQL is even worse there).

What I mean is that when API's spec is not really static, but can be extended. (I am referring to the expression problem https://en.wikipedia.org/wiki/Expression_problem )

On the other topic.

One development idea to you (maybe, you are already doing it, I have not familiarized myself that closely) is to make JSIGHT spec inferencer. Given examples of de facto API calls it may be possible to deduce the spec. Something like JSON schema inferencer https://github.com/rnd0101/json_schema_inferencer , but with JSIGHT as a target.

It's easy to deduce requiredness of fields, but with a smarter inferencer perhaps object can be inferenced as well. Even if the inferencer will not be 100% reliable, it's easy to manually fix the schema / spec.

In a sense, one example is powerful, but when documenting legacy APIs larger bunch of examples is even more descriptive.