Skip to content

Commit 8d06cca

Browse files
wayneeseguinwayneeseguin
committed
Updated README.md
1 parent b04fac9 commit 8d06cca

File tree

1 file changed

+142
-21
lines changed

1 file changed

+142
-21
lines changed

‎README.md‎

Lines changed: 142 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,152 @@
1-
# OpenAPI Specification for CAPI
1+
# Cloud Foundry CAPI OpenAPI Specification
22

3-
This directory contains the OpenAPI specification for the CAPI v3 API.
3+
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.
44

5-
## Flow
6-
1. **Preparation**: Download the CAPI & OpenAPI specs of the designated versions into `specs/{capi,openapi}/{version}.html`.
7-
```bash
8-
make prepare
9-
```
10-
2. **Generate Stubs**: Generate stubs for each CAPI endpoint as defined in the specifications.
5+
## Overview
116

12-
3. Merge stubs into the CAPI OpenAPI specification.
13-
```bash
14-
make gen-openapi-spec
15-
```
16-
This will generate the files `capi/{version}.openapi.yaml` and then `capi/{version}.openapi.json`.
7+
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:
178

18-
4. Generate a client, ex:
19-
```bash
20-
make gen-go-client
21-
```
9+
- Generate client SDKs in multiple languages
10+
- Create API documentation
11+
- Perform API testing and validation
12+
- Build developer tools and integrations
2213

14+
## Features
15+
16+
- ✅ **Complete API Coverage**: All 44 resource types and their endpoints
17+
- ✅ **Modular Architecture**: Organized into separate YAML files per resource
18+
- ✅ **Advanced Querying**: Label selectors, timestamp operators, field selection
19+
- ✅ **Experimental Features**: Marked with `x-experimental` extension
20+
- ✅ **Comprehensive Schemas**: Full request/response schemas with examples
21+
- ✅ **Metadata Support**: Labels and annotations on all resources
22+
- ✅ **Async Operations**: Job tracking for long-running operations
23+
- ✅ **Error Handling**: Detailed error schemas and status codes
24+
25+
## Quick Start
26+
27+
### Prerequisites
28+
- Make
29+
- OpenAPI tools (optional, for validation)
30+
- Your preferred programming language for client generation
31+
32+
### Basic Usage
33+
34+
1. **Clone the repository**
35+
```bash
36+
git clone https://github.com/cloudfoundry-community/capi-openapi-spec.git
37+
cd capi-openapi-spec
38+
```
39+
40+
2. **Generate the unified OpenAPI specification**
41+
```bash
42+
make gen-openapi-spec
43+
```
44+
This creates `capi/3.181.0.openapi.yaml` and `capi/3.181.0.openapi.json`
45+
46+
3. **Generate a client SDK** (example for Go)
47+
```bash
48+
make gen-go-client
49+
```
50+
51+
## Version Information
52+
53+
| Component | Version |
54+
|-----------|---------|
55+
| CAPI API Version | v3.195.0 |
56+
| OpenAPI Specification | 3.0.0 |
57+
| Last Updated | January 2025 |
58+
59+
## Documentation
60+
61+
Comprehensive documentation is available in the `docs/` directory:
62+
63+
- [Getting Started Guide](docs/getting-started.md) - Introduction and quick examples
64+
- [API Overview](docs/api-overview.md) - REST principles, pagination, errors
65+
- [Core Resources Guide](docs/core-resources.md) - Apps, processes, builds, packages
66+
- [Services Guide](docs/services.md) - Service instances, bindings, brokers
67+
- [Query Parameters Guide](docs/query-parameters.md) - Advanced filtering and selection
68+
- [Client SDK Guide](docs/client-sdks.md) - Generating and using client libraries
69+
70+
## Supported Resources
71+
72+
The specification covers all Cloud Foundry v3 resources:
73+
74+
### Core Application Resources
75+
- Applications, Processes, Builds, Droplets, Packages
76+
- Revisions, Deployments, Tasks, Sidecars
77+
78+
### Routing & Networking
79+
- Routes, Domains, Route Destinations
80+
- Security Groups, Route Mappings (deprecated)
81+
82+
### Organizations & Spaces
83+
- Organizations, Spaces, Roles
84+
- Organization Quotas, Space Quotas
85+
- Isolation Segments, Space Features
86+
87+
### Services
88+
- Service Instances, Service Bindings
89+
- Service Brokers, Service Plans, Service Offerings
90+
- Service Route Bindings (experimental)
91+
92+
### Platform Features
93+
- Jobs (async operations), Manifests
94+
- Feature Flags, Environment Variable Groups
95+
- Audit Events, Usage Events
96+
97+
## Experimental Features
98+
99+
Features marked as experimental using the `x-experimental` extension:
100+
- Route sharing between spaces
101+
- Application manifest diff
102+
- Service route bindings
103+
104+
## Development
105+
106+
### Project Structure
107+
```
108+
capi/
109+
├── 3.181.0/
110+
│ ├── apps.yml
111+
│ ├── processes.yml
112+
│ ├── services.yml
113+
│ └── ... (44 resource files)
114+
├── 3.181.0.openapi.yaml (generated)
115+
└── 3.181.0.openapi.json (generated)
116+
```
117+
118+
### Validation
119+
120+
Validate the OpenAPI specification:
121+
```bash
122+
# Using openapi-generator
123+
openapi-generator validate -i capi/3.181.0.openapi.yaml
124+
125+
# Using swagger-cli
126+
swagger-cli validate capi/3.181.0.openapi.yaml
127+
```
128+
129+
### Contributing
130+
131+
1. Fork the repository
132+
2. Create a feature branch
133+
3. Make your changes to the appropriate YAML files
134+
4. Ensure validation passes
135+
5. Submit a pull request
23136

24137
## Resources
25138

26-
Refer to the following files for more information on specific endpoints and their implementations:
27-
- [CAPI v3.181.0 Spec](https://v3-apidocs.cloudfoundry.org/version/3.181.0/index.html)
28-
- [OpenAPI Spec](https://spec.openapis.org/oas/v3.1.1.html)
29-
- [Learn OpenAPI](https://learn.openapis.org/)
139+
- [CAPI v3.195.0 Documentation](https://v3-apidocs.cloudfoundry.org/version/3.195.0/index.html)
140+
- [OpenAPI Specification](https://spec.openapis.org/oas/v3.0.0)
141+
- [Cloud Foundry Community](https://www.cloudfoundry.org/community/)
142+
143+
## License
144+
145+
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
30146

147+
## Acknowledgments
31148

149+
- Cloud Foundry Foundation
150+
- Cloud Foundry CAPI Team
151+
- OpenAPI Initiative
152+
- Community Contributors

0 commit comments

Comments
 (0)