openwhisk-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Carlos Santana <>
Subject Re: Let's maintain and test our Swagger spec
Date Thu, 21 Jun 2018 19:04:28 GMT
Thanks Ben for looking into this, having a good API doc/spec and matching
tests is very need it.



On Thu, Jun 21, 2018 at 2:25 PM Ben Browning <> wrote:

> Our Swagger spec
> (
> )
> 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

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message