Re: Introducing CF-Swagger
Since I know various folks are looking at better API docs. I went ahead
and did some quick investigation on what other kind of docs formats could
be generated from Swagger.
Found a bunch, but experimented with Swagger2Markup and was able to
generate the following from the Service Broker Swagger definition here:
2. GitHub Markdown:
These are generated from the JSON above without any customization or
ibm cloud labs
silicon valley, ca
09/18/2015 04:51 PM
Mohamed Mohamed/Almaden/IBM(a)ibmus, Christopher B Ferris/Waltham/IBM(a)ibmus,
Alex Tarpinian/Austin/IBM(a)ibmus, Heiko Ludwig/Watson/IBM(a)ibmus
This email serves two purposes: 1) introduce CF-Swagger, and 2) shares the
results of the CF service broker compliance survey I sent out a couple of
My IBM Research colleague, Mohamed (on cc:), and I have been working on
creating Swagger descriptions for some CF APIs.
Our main goal was to explore what useful tools or utilities we could build
with these Swagger descriptions once created.
The initial results of this exploratory research is CF-Swagger which is
included in the following:
See presentation here: https://goo.gl/Y16plT
Video demo here: http://goo.gl/C8Nz5p
Temp repo here: https://github.com/maximilien/cf-swagger
The gist of of our work and results are:
1. We created a full Swagger description of the CF service broker
2. Using this description you can use the Swagger editor to create a neat
API docs that is browsable and even callable
3. Using the description you can create client and server stubs for
service brokers in a variety of languages, e.g., JS, Java, Ruby, etc.
4. We've extended go-swagger to generate workable client and server stubs
for service brokers in Golang. We plan to submit all changes to go-swagger
back to that project
5. We've extended go-swagger to generate prototypes of working Ginkgo
tests to service brokers
6. We've extended go-swagger to generate a CF service broker Ginkgo Test
Compliance Kit (TCK) that anyone could use to validate their broker's
compliance with any Swagger-described version of spec
7. We've created a custom Ginkgo reporter that when ran with TCK will give
you a summary of your compliance, e.g., 100% compliant with v2.5 but 90%
compliant with v2.6 due to failing test X, Y, Z... (in Ginkgo fashion)
8. The survey results (all included in the presentation) indicate that
over 50% of respondants believe TCK tests for service broker would be
valuable to them. Many (over 50%) are using custom proprietary tests, and
this project maybe a way to get everyone to converge to a common set of
tests we could all use and improve...
We plan to propose this work to become a CF incubator at the next CAB and
PMC calls, especially the TCK part for service brokers. The overall
approach and project could be useful for other parts of the CF APIs but we
will start with CF Service Brokers.
The actual Swagger descriptions should ideally come from the teams who own
the APIs. So for service brokers, the CAPI team. We are engaging them as
they have also been looking at improving APIs docs and descriptions. Maybe
there are potential for synergies and at a minimum making sure what we
generate ends up becoming useful to their pipelines.
Finally, while the repo is temporary and will change, I welcome you to
take a look at presentation and video and code and let us know your
thoughts and feedback.
Thanks for your time and interest.
Mohamed and Max