Our Swagger spec (https://github.com/apache/incubator-openwhisk/blob/92a64c291156a2cd3d6b304babc2a193a46d0699/core/controller/src/main/resources/apiv1swagger.json) is incomplete and doesn't accurately reflect the actual Controller API. It's manually updated without a full test suite which means it's easy for changes in the API to happen without the spec getting updated.
An accurate Swagger spec will not only better document the OpenWhisk API but also allow autogenerated clients in multiple languages to supplement or eventually replace some of the existing client implementations we have today. It also paves way for future compatible server implementations, whether they be rewrites of the existing Controller or stub test harnesses to facilitate end-to-end testing on a developer's laptop. As I'm already working with autogenerating code from the Swagger spec for other purposes, I'm happy to take the lead on this effort. I'd like to take a two-pronged approach for a test suite: * Generate a server stub from the spec and ensure the wsk CLI can communicate with it. * Generate a client stub from the spec and ensure it can communicate with the existing API. There are a lot of details to figure out from those two statements. And, this approach won't guarantee 100% correctness of the spec. The only way to do that would be to generate all supported clients and the Controller API from the spec. But, this should get us started in the right direction. If anyone's gone down this path before and has some wisdom to share, please speak up! Thanks, Ben
