As mentioned yesterday, @blocktrades wants to move over to OpenAPI for API documentation. So, I looked into it, and apparently this is basically what it will look like, once generated:
See all currently generated documents: https://hackmd.io/P67pyxzKSquMDCDeCmIjYQ?view#bridge_list_all_subscriptions
For comparison, here is what the existing documentation says on the same topic:
See: https://developers.hive.io/apidefinitions/#bridge.list_all_subscriptions
Both documentation examples answer this simple question: "How do I get a list of all subscriptions for a particular account?"
The OpenAPI version shows a large block of python code while the existing version yields a curl that succinctly demonstrates the same thing.
The OpenAPI version reminds me more of a self-contained python tutorial while the existing version is very much language-agnostic.
I think both approaches are good, but I don't see a reason to do one or the other. As I mentioned previously, I already have the tools in the devportal to verify which methods are documented. I could easily hook into OpenAPI as an additional source for verification.
If the hivemind/hive developers prefer using OpenAPI, this in no way detracts from the devportal's use case. Instead, it extends the ability for devportal to become more accurate by giving devportal maintainers even more context.
In fact, devportal could pull in the OpenAPI annotations, become aware of these methods, and link to the site that hosts them:
If you're working in node.js, the python examples are not much help. That's why the devportal shows a curl example and has tutorials on language-specific solutions.
If you'd like to vote for my current proposal:
https://hivesigner.com/sign/update-proposal-votes?proposal_ids=[151]&approve=true
Also see: https://peakd.com/proposals/inertia