A complete OpenAPI 3.0.0 specification for the Cloud Foundry Cloud Controller API (CAPI) v3.195.0, providing 100% coverage of all API endpoints, resources, and operations.
This treats the upstream Cloud Foundry API v3 as the source of truth: https://v3-apidocs.cloudfoundry.org/version/3.195.0/index.html#deprecated-endpoints
The api docs are fetched from the versioned url into the ./data directory and then processed into the OpenAPI YAML files in ./capi/3.195.0.
Currently the process of carving up the API html file into the individual YAML files is done manually, the goal is to automate this part of the process in the future.
Once this has been parsed into the OpenAPI .yml files in ./capi/3.195.0 they are then merged into ./capi/3.195.0.openapi.yaml and .capi/3.195.0.openapi.json files.
From there the OpenAPI specification can be used to generate client SDKs, documentation, etc...
This repository contains a comprehensive OpenAPI specification that fully describes the Cloud Foundry v3 API. The specification is organized into modular YAML files for maintainability and can be used to:
- Generate client SDKs in multiple languages
- Create API documentation
- Perform API testing and validation
- Build developer tools and integrations
- ✅ Complete API Coverage: All 44 resource types and their endpoints
- ✅ Modular Architecture: Organized into separate YAML files per resource
- ✅ Advanced Querying: Label selectors, timestamp operators, field selection
- ✅ Experimental Features: Marked with
x-experimentalextension - ✅ Comprehensive Schemas: Full request/response schemas with examples
- ✅ Metadata Support: Labels and annotations on all resources
- ✅ Async Operations: Job tracking for long-running operations
- ✅ Error Handling: Detailed error schemas and status codes
- Make
- OpenAPI tools (optional, for validation)
- Your preferred programming language for client generation
-
Clone the repository
git clone https://github.com/cloudfoundry-community/capi-openapi-spec.git cd capi-openapi-spec -
Install dependencies
make deps
-
Generate the unified OpenAPI specification
make gen-openapi-spec
This creates
capi/3.195.0.openapi.yamlandcapi/3.195.0.openapi.json -
Generate a client SDK (example for Go)
make gen-go-client # Or for any language: make gen-sdk LANGUAGE=python VERSION=3.195.0
The bin/gen script provides a flexible way to generate SDKs for different languages and CAPI versions.
# Generate SDK
./bin/gen --version=VERSION --language=LANGUAGE [--output=PATH]
# Prepare specifications (download and create YAML files)
./bin/gen prepare --version=VERSION
# Merge YAML files into unified OpenAPI spec
./bin/gen merge --version=VERSION./bin/gen --version=3.195.0 --language=go
# Output: ./sdk/3.195.0/go/./bin/gen --version=3.195.0 --language=ruby
# Output: ./sdk/3.195.0/ruby/./bin/gen --version=3.195.0 --language=python --output=/path/to/my-sdk# Go SDK for CAPI 3.181.0
./bin/gen --version=3.181.0 --language=go
# Ruby SDK for CAPI 3.181.0
./bin/gen --version=3.181.0 --language=rubyThe generator supports all languages provided by OpenAPI Generator, including:
- go - Go client library
- ruby - Ruby gem
- python - Python package
- java - Java library
- javascript - JavaScript/Node.js
- typescript-node - TypeScript for Node.js
- csharp - C# / .NET
- php - PHP library
- rust - Rust crate
- swift5 - Swift 5
- kotlin - Kotlin
- And many more...
Run ./bin/gen --help to see the full list of supported languages.
After generating an SDK, you may need to:
- Go: Run
go mod tidyin the generated directory - Ruby: Build the gem with
gem build *.gemspec - Python: Install with
pip install -e . - Java: Build with Maven or Gradle
| Component | Version |
|---|---|
| CAPI API Version | v3.195.0 |
| OpenAPI Specification | 3.0.0 |
| Last Updated | January 2025 |
Comprehensive documentation is available in the docs/ directory:
- Getting Started Guide - Introduction and quick examples
- API Overview - REST principles, pagination, errors
- Core Resources Guide - Apps, processes, builds, packages
- Services Guide - Service instances, bindings, brokers
- Query Parameters Guide - Advanced filtering and selection
- Client SDK Guide - Generating and using client libraries
The specification covers all Cloud Foundry v3 resources:
- Applications, Processes, Builds, Droplets, Packages
- Revisions, Deployments, Tasks, Sidecars
- Routes, Domains, Route Destinations
- Security Groups, Route Mappings (deprecated)
- Organizations, Spaces, Roles
- Organization Quotas, Space Quotas
- Isolation Segments, Space Features
- Service Instances, Service Bindings
- Service Brokers, Service Plans, Service Offerings
- Service Route Bindings (experimental)
- Jobs (async operations), Manifests
- Feature Flags, Environment Variable Groups
- Audit Events, Usage Events
Features marked as experimental using the x-experimental extension:
- Route sharing between spaces
- Application manifest diff
- Service route bindings
capi/
├── 3.195.0/
│ ├── apps.yml
│ ├── processes.yml
│ ├── services.yml
│ └── ... (41 resource files)
├── 3.195.0.openapi.yaml (generated)
└── 3.195.0.openapi.json (generated)
bin/
├── gen (main processing script for prepare, merge, and SDK generation)
└── validate (OpenAPI spec validation script)
sdk/
└── VERSION/
└── LANGUAGE/ (generated SDKs)
Validate the OpenAPI specification:
# Using openapi-generator
openapi-generator validate -i capi/3.195.0.openapi.yaml
# Using swagger-cli
swagger-cli validate capi/3.195.0.openapi.yaml- Fork the repository
- Create a feature branch
- Make your changes to the appropriate YAML files
- Ensure validation passes
- Submit a pull request
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- Cloud Foundry Foundation
- Cloud Foundry CAPI Team
- OpenAPI Initiative
- Community Contributors