Move cf-openapi into CCNG#5287
Open
sethboyles wants to merge 90 commits into
Open
Conversation
- Support oapi-codegen as default Go generator (creates cleaner single-file client) - Add bin/publish script to publish versioned Go clients to dedicated repository - Configure GitHub Actions workflow for automated publishing - Add operationId fields to CAPI endpoints for better SDK generation - Auto-generate go.mod with proper module paths and dependencies
This commit introduces a complete overhaul of the OpenAPI specification generation
process, moving from manual YAML maintenance ('curateion' 🤪) to automated
extraction from CAPI HTML documentation.
Key changes:
- Added Perl-based HTML parsing infrastructure for extracting API schemas
- Implemented test suite with initial edge case handling
- Generated documentation covering the generation toolchain and process
- Introduced automated validation, enhancement, and error fixing scripts
- Added support for multiple SDK language generation
- Restructured project to support versioned specifications
- Removed incomplete 3.181.0 spec work in favor of generated 3.195.0
- Added GitHub Actions workflows for CI/CD, monitoring, and SDK generation
The new system automatically:
- Parses CAPI HTML docs to extract endpoints, schemas, and examples
- Generates valid OpenAPI 3.1.1 specifications
- Validates and enhances specs with proper types and constraints
- Generates client SDKs for multiple languages
- Monitors CAPI releases for updates
I tried moving forward with either of both repos but eventually i just ended up rewriting major things from scratch. Pushing this now so it can be discussed as part of the ongoing cf community RFC
Flag experimental
* CF returns a list of errors rather than a single error * Add missing paths to openapi.yaml * Add missing resource schema * Add missing requestBodies * Change to use path references rather than hash references * Add missing response body schemas * Add lint ignore for endpoint that returns 302
Various improvements
* Fix get space parameters * Fix erronous space request body to isolation seg
Add link to rendered OpenAPI specification.
Fixes from request spec validation
Fix support for included
Reuse exisiting errors schema
Add missing set role by username feature
Add role resources schema as included will not be returned in role list responses. Update organization list to include pagination as a property Update users path ti use user list as paginatedusers contains extra properties not returned from the api
Fixes for List Support
User guids can be client ids
* Update openapi schema changes of Deployment and Processes * Update apis/cf/latest/components/schemas/Deployment.yaml * Update apis/cf/latest/paths/Deployments.yaml * Update apis/cf/latest/paths/Deployments.yaml --------- Co-authored-by: Sam Gunaratne <385176+Samze@users.noreply.github.com>
The OpenAPI link for retrieving the droplet was using the path
$response.body#/droplet/data/guid, but the actual REST response
structure has the GUID directly under droplet:
"droplet": { "guid": "..." }
Changed the path to $response.body#/droplet/guid to match the
actual API response.
…1050) CCNG routes.rb only defines PATCH for replacing route destinations (routes#replace_destinations). The PUT method documented in the spec does not correspond to any route in cloud_controller_ng and would result in a 404 if called. The PATCH method (operationId: replaceDestinationsForRouteWithPatch) remains and is the correct way to replace destinations. Made-with: Cursor
This endpoint exists in CCNG routes.rb and returns a simplified view of process instances (index, state, since) compared to the /stats endpoint which returns detailed resource usage. Added the path definition to Processes.yaml and wired it into openapi.yaml. Made-with: Cursor
…ment organizations (#1048) Two endpoints exist in cloud_controller_ng routes.rb but were missing from the OpenAPI specification: 1. GET /v3/spaces/{guid}/usage_summary - public endpoint analogous to the already-documented GET /v3/organizations/{guid}/usage_summary. Added path definition to Spaces.yaml and wired into openapi.yaml. 2. GET /v3/isolation_segments/{guid}/organizations - path definition already existed in IsolationSegments.yaml but was not referenced from openapi.yaml paths section. Added the $ref to make it visible to spec consumers. Made-with: Cursor
* Add IndexLink schema to handle index link's metadata field * Reduce Schema Drift and have IndexLink inherit from link Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * V3 api root does not have the meta field * Reference to Link object --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
…#1053) * Introduce oasdiff and oasdiff breaking changes workflow on PR to main * Address security and performance feedback in breaking-changes workflow - Restrict token permissions with `permissions: contents: read` - Prevent token persistence in checkout steps - Use `npm ci --ignore-scripts` to mitigate malicious lifecycle scripts - Implement dependency caching for `npm` to speed up workflow - Add concurrency limits to prevent redundant workflow runs - Add a 10 minute job timeout Co-authored-by: Cursor <cursoragent@cursor.com> * Update breaking-changes workflow to use Node 22 and Yarn caching Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com>
- Add curated examples from ccng/docs to our latest components - Fix schema lint errors and app links warnings - Remove trailing quote for router group description markdown Co-authored-by: Cursor <cursoragent@cursor.com>
cf-openapi's workflows lived under docs/openapi/.github/workflows, which GitHub Actions never reads (only .github/workflows at repo root is discovered). Move test, breaking-changes, and deploy workflows to the root, scoped to docs/openapi/** via path filters and working-directory.
…eploy Repo's Pages site is already published from the gh-pages branch by deploy_v3_docs.yml (which uploads the whole branch as the Pages artifact). A second, independent deploy-pages call for the openapi docs would race with it and overwrite whichever deployed last. Instead, build the openapi docs and commit them into gh-pages/openapi/, letting the existing workflow pick them up and publish everything together.
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Comment on lines
+17
to
+38
| name: Test | ||
| runs-on: ubuntu-latest | ||
| container: | ||
| image: node:24-alpine | ||
| defaults: | ||
| run: | ||
| working-directory: docs/openapi | ||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v4 | ||
| - name: Setup | ||
| run: | | ||
| apk add python3 make g++ | ||
| yarn install | ||
| - name: Stats | ||
| run: yarn redocly stats --format markdown >> $GITHUB_STEP_SUMMARY | ||
| - name: Lint | ||
| run: | | ||
| yarn redocly lint --max-problems 9999 --format markdown >> $GITHUB_STEP_SUMMARY || true | ||
| yarn redocly lint --max-problems 9999 --format github-actions | ||
| - name: Build | ||
| run: yarn build |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
9 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
One of the steps to make the OpenAPI spec the primary docs for V3 is to move the separate repo to CCNG. This PR adds the openapi docs to a subdirectory
docs/openapi, with the commit history of the original repo intact.Thanks to @geofffranks for showing me how to do this. It was quite easy:
This also changes the github actions workflow for publishing docs to publish both v3 and the OpenAPI docs at the same time. The OpenAPi docs will be deployed at the
/openapiGH pages subdirectory.