Repository navigation
Replace V3 docs with OpenAPI docs #5093
Description
We have an experimental OpenAPI spec/documenation here: https://cloudfoundry.github.io/cf-openapi/#description/more-resources
I'd be nice to replace our existing V3 documentation with these docs.
It'd be nice to somehow validate the accuracy of the OpenAPI docs, as well as merge in the docs to the core CCNG codebase so that new features do not need to be spread apart separate codebases.
There are also missing pieces of the current documentation that are not in the OpenAPI docs (like Valid Role Types)
Things to do before replacing the current docs
non-exhaustive list:
- Host openapidocs at something like
openapi-docs.cloudfoundry.org - Validate correctness of spec in some way.
- Add missing areas:
- Move OpenAPI docs to CCNG codebase
We might need to go section-by-section to compare what else is missing from the OpenAPI docs
Activity
norman-abramovitz commentedon Jun 15, 2026
For the "validate correctness of the spec" item: I compared
apis/cf/latestagainst a contract model I extract from the published v3 docs (233 shared operations), and the spec held up well. Coverage is basically complete — the only gaps I saw were artifacts of my own extractor, and the spec actually has some app-scoped aliases the rendered docs miss (scaleProcessForApp,getProcessForApp, etc).The more useful result: on status codes the spec is more accurate than the v3 docs it would replace. Three endpoints document
201 Createdbut the controller renders200 OK, and cf-openapi already has all three right:GET /v3/rolesPATCH /v3/users/:guidPOST /v3/organization_quotas/:quota_guid/relationships/organizationsThe first two were fixed in #5185. I opened #5190 for the org-quota one. Seems like a decent point in favor of the migration here.
A few I couldn't resolve from the controller alone, in case they're worth a look:
uploadBuildpack/uploadDroplet— spec lists 200 and 202; the controller only renders:accepted(202).uploadPackageBits— spec lists 200 and 202; controller renders:ok(200).createManifestDiff— spec lists 201 and 202; controller renders:created(201).These might be intentional if uploads can be sync or async depending on config — just flagging in case they're not.
sethboyles commentedon Aug 24, 2026
Heads up, the merge of the openapi docs into this repo (#5287) didn't quite work as expected. You won't see all the individual commits as normal, but the history is there if you run
git log --full-history -- docs/openapinorman-abramovitz commentedon Oct 20, 2026
Closing the loop on my June comment: the four operations I flagged as "might be config-dependent" (
uploadBuildpack,uploadDroplet,uploadPackageBits,createManifestDiff) aren't; each controller renders one fixed status (details with code links on #5496, whose draft changes address all four). A full cross-check ofdocs/openapiagainst the v3 docs, CC's routes and the controllers found 37 discrepancies at 3.229.0; 30 still apply on main (12d614d). The draft #5496 addresses all 28 that are on the OpenAPI side; one more (service_instance_guidsonGET /v3/apps/{guid}/routes) is in neither doc, and one is a v3-docs gap (PATCH /v3/apps/:guid/processes/:type). Details on #5496.