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

cloudfoundry / cloud_controller_ng

Cloud Foundry Cloud Controller

Apache License 2.0

191 stars 357 forks source link

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

Open gberche-orange opened 3 years ago

gberche-orange commented 3 years ago

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 https://github.com/cloudfoundry/cc-api-v3-style-guide/issues/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 https://github.com/cloudfoundry/cloud_controller_ng/issues/939 which was closed in favor of https://github.com/cloudfoundry/cc-api-v3-style-guide/issues/46

cf-gitbot commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 8 months ago

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 commented 3 weeks ago

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.