Not sure about recommended way, but Swagger above uses methods from blockchain directly as they are available, only we run small proxy to format those APIs so it could be accessed right within browser (GET ops). And yes, I think it would be really beneficial to have them inside devportal next to curl examples, test right on browser (for users without terminal or chromebook, etc. systems)
RE: Interactive Hive API moved to Hivesigner