Feature request: Machine-readable api documentation

[jmcarp]

As a consumer of the cloud foundry api, I want api clients in multiple languages that are current and complete. A handful of clients exist, like https://github.com/cloudfoundry-community/go-cfclient and https://github.com/cloudfoundry-attic/cfoundry, but are incomplete and/or unmaintained. It would be ideal if api clients could be generated automatically from some kind of machine-readable markup, such as swagger, raml, etc. This would be very useful to the community, and would also save time upstream--api documentation and some tests could also be auto-generated as well.

I saw that this was discussed a while back in #455 and closed without a clear resolution, so I thought I'd bring it up again and see if there was interest.

cc @cnelson

[cf-gitbot]

We have created an issue in Pivotal Tracker to manage this:

https://www.pivotaltracker.com/story/show/140165817

The labels on this github issue will be updated when the story is started.

[jmcarp]

Since you're using rspec_api_documentation, it should be possible to add swagger documentation without much trouble by implementing zipmark/rspec_api_documentation#216.

[zrob]

Hi @jmcarp

Our current goals for docs is to have new endpoints documented here and then eventually move all previous endpoints over. We don't currently have plans to maintain any machine readable markup, though I do understand the benefit that can have for clients. We're currently working under the premise that setting up the models and and requests is easier than understanding how to coordinate the many requests required to complete common workflows -- pushing an app, creating and mapping routes -- which we plan to explicitly document in our Workflows section of the linked docs.

I have spent some time playing with json schema and have found it useful, but don't have any near term plans to maintain a schema of our own.

You may also be interested in tracking the cli client that is being built up for the v3 api.

[jmcarp]

@zrob: are the new docs built from an rspec dsl like the v2 docs?

[zrob]

@jmcarp they're generated from markdown using slate: https://github.com/cloudfoundry/cloud_controller_ng/tree/master/docs/v3