Thanks Ben for looking into this, having a good API doc/spec and matching
tests is very need it.

+1

-cs

On Thu, Jun 21, 2018 at 2:25 PM Ben Browning <bbrownin@redhat.com> wrote:

> 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
>