Formal specs for CC API V3 enabling automated client generation & API ecosystem tooling

[gberche-orange]

Issue

As an CAPI user

• in order to leverage off-the-shelf API ecosystem tooling (API Web clients, API SDK, Pen testing tools ...)
• I need CAPI to publish API documentation into a standard API specification processable by machine (typically openAPI)

Context

This enhancement request was tracked since 2015 on cloudfoundry/cc-api-v3-style-guide#46 and postponed until CAPI V3 is out.

Reopening this issue since https://github.com/cloudfoundry/cc-api-v3-style-guide repo was archived on April 9th, 2021

Experimental community swagger CAPI V2 API specifications was contributed in the past at https://github.com/cloudfoundry-attic/cf-swagger

This was also requested in CC_NG in #939 which was closed in favor of cloudfoundry/cc-api-v3-style-guide#46

[cf-gitbot]

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

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

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

[gregorwolf]

Would be great to see the API documented using Open API. I need to use the API in a Node.JS project running on SAP Business Technology Platform - Cloud Foundry Environment. There is a TypeScript project cf-http-client that currently has a very limited scope. Also there is @sap/cf-tools. But @sap/cf-tools requires the Cloud Foundry CLI to be installed.

[damzog]

Our use case is that we think about exposing a subset of commands of the capi (for managing apps and services) to less secure origins by using an api management tool. In order to achieve that we require a swagger file of (a subset of functions of) the api.

One of my ideas was to look at https://github.com/cloudfoundry/cloud_controller_ng/tree/master/spec/api/documentation to generate a swagger file. What are your thoughts about it?

[mogul]

There's now Terraform tooling for auto-generating a provider based on an OpenAPI spec. I got excited about that until I found this issue and realized there was no OpenAPI spec for the CC v3 API. 😞

[FloThinksPi]

Just for reference i`m trying some things out over at https://github.com/FloThinksPi/cf-api-openapi-poc see also community slack https://cloudfoundry.slack.com/archives/C07C04W4Q/p1724693872392509
Once thats mature/is correct in some way we can discuss merging it to the CF project.

Im not sure if the entire v3 api can be described as an openapi spec yet. However most of it should be possible.