Document the API using Swagger

[cgfrost]

For people implementing clients to the API the documentation is the only resource available. It several areas the quality of the documentation is very poor meaning ambiguity can creep in to implementations. It also takes a lot of time write an implementation and a machine readable format would help speed things up. Finally, a machine readable format would help with testing of a client library against a particular version of the specification.

So far I'm aware of Java and Node based clients being created and I imagine the CLI implementations could benefit as well. Swagger is the de-facto format for specifying APIs and includes a great viewer for navigating an API. http://swagger.io/

[cf-gitbot]

We have created an issue in Pivotal Tracker to manage this. You can view the current status of your issue at: https://www.pivotaltracker.com/story/show/106128498.

[dieucao]

Hi Chris,
As mentioned in other threads we are looking to improve the api documentation.
We spent time investigating api documentation options including using swagger [1], api blueprint, or going a little more freeform.
My goals for the api documentation were for it to be clear, correct and easy for the dev team to maintain.
We have an initial story to try going the more freeform route with slate (which is similar in look and feel to stripe's api documentation [2]) In reviewing different api docs out in the wild, I very much like github's api documentation and stripe's api documentation.

I've recently been seeing more requests like yours to use swagger to help with client generation and verification.
I'm concerned we may end up spending a lot of time attempting to define the api in swagger format and while I understand this can be helpful for client developers, that's more scope than what I would like the team to take on at this time.

[1] https://www.pivotaltracker.com/story/show/104040832
[2] https://stripe.com/docs/api

[cgfrost]

Hi,

I hadn't come across Slate before. It looks like it would also be an improvement. While being able to generate stubs/tests from a Swagger file would be good I understand the extra work that would involve. Slate would be much appreciated. Thanks for the quick response.