Skip to content

[RFC] Document CF API V3 with OpenAPI #1256

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 2, 2025
Merged

[RFC] Document CF API V3 with OpenAPI #1256

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9a88f23
[RFC] Document CF API with OpenAPI
FloThinksPi Jul 23, 2025
b337168
Added review comments
FloThinksPi Aug 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 92 additions & 0 deletions toc/rfc/rfc-draft-document-cf-api-with-openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
# Meta

- Name: Documenting the CF API with OpenAPI
- Start Date: 2025-07-23
- Author(s): @flothinkspi
- Status: Draft
- RFC Pull Request: [community#1256](https://github.com/cloudfoundry/community/pull/1256)

## Summary

With the acceptance of
[RFC-32](https://github.com/cloudfoundry/community/blob/d7b48620d0da3bcadeea18aaf64f6fa36c329e7f/toc/rfc/rfc-0032-cfapiv2-eol.md),
a problem arises for users of CF who rely on unsupported client
libraries that are not maintained and just work with the deprecated CF V2 API. To ensure the success of
[RFC-32](https://github.com/cloudfoundry/community/blob/d7b48620d0da3bcadeea18aaf64f6fa36c329e7f/toc/rfc/rfc-0032-cfapiv2-eol.md)
and to enable users to better transition to the V3 API, and also future-proof the CF API documentation, this RFC proposes
to document the CF API V3 using the OpenAPI specification.

## Problem

## Motivation

1. Improve the overall CF user experience, increasing the adoption and
popularity of CloudFoundry.

2. Support the adoption of
[RFC-32](https://github.com/cloudfoundry/community/blob/d7b48620d0da3bcadeea18aaf64f6fa36c329e7f/toc/rfc/rfc-0032-cfapiv2-eol.md)
by offering an more user-friendly path for users away from the CF V2 API.

3. Provide a widely adopted documentation format (OpenAPI) that enables many new usecases from programatic access to the CF API docs and schema to generating Documentation pages, automatic tests of documentation vs implementation or also better AI Agent integration.

## Proposal

### Documenting the CF V3 API with OpenAPI

With [OpenAPI](https://www.openapis.org/), APIs can be defined in a
machine-readable format (YAML), enabling the generation of client
libraries for various programming languages and the rendering of
interactive HTML API documentation. The OpenAPI specification is widely
adopted and supported by many tools. A [Proof of Concept
(PoC)](https://github.com/FloThinksPi/cf-api-openapi-poc) and [another Proof of Concept](https://github.com/cloudfoundry-community/capi-openapi-spec) is already
exploring the documentation of the CF V3 API as an OpenAPI spec,
providing a glimpse (currently with incorrect content) of the potential
look and feel of this documentation format.

The CloudFoundry organization MAY document the CF API V3 using the
OpenAPI specification. Which then can be used by CF Maintainers or CF Users to
leverage a huge toolchain around OpenAPI to generate client libraries, documentation pages, and more. This MAY render a transition like for example from a unsupported client library that only supports the CF V2 api towards using the CF V3 api a lot more easier since the available toolchain around OpenAPI is big, valuable, a time saver and then available to CF Users.
Such usecases include for example:

- [Swagger UI](https://swagger.io/tools/swagger-ui/) for interactive API documentation.
- [Swagger Codegen](https://swagger.io/tools/swagger-codegen/) for generating client libraries
- [OpenAPI Generator](https://openapi-generator.tech/) for generating client libraries and server stubs in various languages.
- [Redoc](https://redocly.com/redoc/) for generating static API documentation.
- [Postman](https://www.postman.com/) for API testing and documentation.
- [Dredd](https://dredd.org/en/latest/) for testing API documentation against the implementation.
- [AI Agents](https://github.com/janwilmake/openapi-mcp-server) for improved integration with AI-powered tools.

### Phases

Copy link
Contributor

@Samze Samze Jul 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thought https://github.com/rswag/rswag would be an interesting approach, create request specs that can be used to generate open api spec. That way we get a open api doc and some verification in a single definition. However that would mean creating/updating whole bunch of requests specs.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried that before the issue with that is that we dont use native rails - e.g. we dont use active records but sequel library for the models. Rswag just worked for me when its a absolute default ruby project. But i also like to give it a shot again since i last tried it 1-2 years ago. Optimally we could use something like that but in any case writing the OpenAPI spec by hand is already an improvement from writing the HTML/MD page oneself i guess. Especially for the consumer side the format is the only thing that matters. How its produced is secondary for a CF consumer, relevant for the Working Group though.

**Implementation** - Convert <https://github.com/cloudfoundry-community/capi-openapi-spec> to a repository in the official cloudfoundry organization.Document the CF API V3 using the OpenAPI specification. Also generate a html documentation to replace the current page. Optionally build up, if possible, a validation(integration test) that validates if the OpenAPI spec is in sync with the actual implementation of the CF API V3.

**Checkpoint** - TOC review and approval of the project, ensuring the
OpenAPI documentation is complete in comparison to the current one and of appropriate quality. Replacement of the current CF API V3 website with representing the OpenAPI spec. Also release the OpenAPI spec for programmatic access to the CF API V3 documentation.

## Impact and Consequences

### Positive

- CF may see an increase in adoption and popularity due to improved
usability and user experience and the use of a documentation format
(OpenAPI) that is widely adopted in the industry and integrates well
with other tools. The time needed to develop against the CF API may
decrease, leading to faster implementation for users and increased statisfaction.

- The OpenAPI documentation format empowers users with unique
requirements to generate their own client libraries or starter
templates, providing an exceptional user experience for specialized
use cases.

- The OpenAPI documentation enables programmatic access to the CF API
documentation and schema, allowing for automatic tests of
documentation vs implementation, and better AI Agent integration. A lot of new usecases and adoption may arise from this.

- May reduce backpressure onto
[RFC-32](https://github.com/cloudfoundry/community/blob/d7b48620d0da3bcadeea18aaf64f6fa36c329e7f/toc/rfc/rfc-0032-cfapiv2-eol.md)
due to better enabling of users to transition to the V3 API.

### Negative

- The CloudFoundry organization will have to invest time and resources
to document the CF API V3 using the OpenAPI specification and work on two documentation formats in parallel until the OpenAPI is so mature that it can fully replace the existing documentation.