Skip to content

Commit 59edff5

Browse files
mervinnirmaljohnmervinnirmaljohn
committed
Create open-api yaml for cf-networking policies
1 parent d4240b0 commit 59edff5

11 files changed

Lines changed: 959 additions & 9 deletions

File tree

‎docs/swagger/README.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# CF Networking API Documentation
2+
3+
This directory contains the OpenAPI documentation for the Cloud Foundry Networking API.
4+
5+
## Generated Files
6+
7+
- **`openapi.yaml`** - OpenAPI 3.1 specification in YAML format
8+
- **`openapi.json`** - OpenAPI 3.1 specification in JSON format
9+
- **`index.html`** - Swagger UI viewer for the documentation
10+
- **`README.md`** - This documentation file
11+
12+
## API Overview
13+
14+
The CF Networking API provides endpoints for managing network policies and tags in Cloud Foundry:
15+
16+
### 🔐 Authentication
17+
18+
All endpoints require OAuth2 authentication with appropriate scopes:
19+
- **`network.admin`** - Full access to all policy operations
20+
- **`network.write`** - Write access to policies (for space developers)
21+
22+
### 📋 Endpoints
23+
24+
| Method | Path | Description | Required Scope |
25+
|--------|------|-------------|----------------|
26+
| GET | `/policies` | List network policies | `network.write` |
27+
| POST | `/policies` | Create network policies | `network.write` |
28+
| POST | `/policies/delete` | Delete network policies | `network.write` |
29+
| GET | `/tags` | List tag mappings | `network.admin` |
30+
31+
## Viewing the Documentation
32+
33+
### Option 1: Swagger Editor (Online)
34+
1. Go to [https://editor.swagger.io/](https://editor.swagger.io/)
35+
2. Copy the content of `openapi.yaml` and paste it in the editor
36+
37+
### Option 2: Local Swagger UI
38+
1. Serve this directory with a local web server:
39+
```bash
40+
# Using Python
41+
python -m http.server 8000
42+
43+
# Using Node.js
44+
npx http-server
45+
46+
# Using Go
47+
go run -m http.FileServer -addr=:8000 .
48+
```
49+
2. Open http://localhost:8000 in your browser
50+
51+
### Option 3: Swagger UI Docker
52+
```bash
53+
docker run -p 8080:8080 -v $(pwd):/usr/share/nginx/html -e SWAGGER_JSON=/openapi.json swaggerapi/swagger-ui
54+
```
55+
56+
## Regenerating Documentation
57+
58+
To regenerate the OpenAPI specification after code changes:
59+
60+
```bash
61+
./scripts/generate-swagger.sh
62+
```
63+
64+
This script will:
65+
1. Install `swaggo/swag` v2 if not present
66+
2. Scan the CF Networking codebase for Swag comments
67+
3. Generate OpenAPI 3.1 files: `openapi.yaml` and `openapi.json`
68+
69+
## API Usage Examples
70+
71+
### Authentication
72+
```bash
73+
# Get OAuth token
74+
export TOKEN=$(cf oauth-token)
75+
76+
# Use with API
77+
curl -H "Authorization: $TOKEN" \
78+
https://api.bosh-lite.com/networking/v1/external/policies
79+
```
80+
81+
### List Policies
82+
```bash
83+
curl -H "Authorization: $TOKEN" \
84+
"https://api.bosh-lite.com/networking/v1/external/policies"
85+
```
86+
87+
### Create Policy
88+
```bash
89+
curl -H "Authorization: $TOKEN" \
90+
-H "Content-Type: application/json" \
91+
-X POST \
92+
-d '{
93+
"policies": [
94+
{
95+
"source": {"id": "app-1-guid"},
96+
"destination": {
97+
"id": "app-2-guid",
98+
"protocol": "tcp",
99+
"ports": {"start": 8080, "end": 8080}
100+
}
101+
}
102+
]
103+
}' \
104+
"https://api.bosh-lite.com/networking/v1/external/policies"
105+
```
106+
107+
## Schema Information
108+
109+
The API uses these main data structures:
110+
111+
- **Policy** - Defines network connectivity between source and destination applications
112+
- **Source/Destination** - Application identifiers and network configuration
113+
- **Ports** - Port range specification (start/end)
114+
- **Tag** - Unique identifier assigned to policy groups
115+
- **PoliciesPayload** - Container for multiple policies with count information
116+
117+
For detailed schema information, see the generated `openapi.yaml` file or view in Swagger UI.

‎docs/swagger/index.html‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<title>CF Networking API Documentation</title>
5+
<link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3.52.5/swagger-ui.css" />
6+
<style>
7+
html {
8+
box-sizing: border-box;
9+
overflow: -moz-scrollbars-vertical;
10+
overflow-y: scroll;
11+
}
12+
*, *:before, *:after {
13+
box-sizing: inherit;
14+
}
15+
body {
16+
margin:0;
17+
background: #fafafa;
18+
}
19+
</style>
20+
</head>
21+
<body>
22+
<div id="swagger-ui"></div>
23+
24+
<script src="https://unpkg.com/swagger-ui-dist@3.52.5/swagger-ui-bundle.js"></script>
25+
<script src="https://unpkg.com/swagger-ui-dist@3.52.5/swagger-ui-standalone-preset.js"></script>
26+
<script>
27+
window.onload = function() {
28+
// Load the OpenAPI 3.x spec
29+
const ui = SwaggerUIBundle({
30+
url: './openapi.yaml',
31+
dom_id: '#swagger-ui',
32+
deepLinking: true,
33+
presets: [
34+
SwaggerUIBundle.presets.apis,
35+
SwaggerUIStandalonePreset
36+
],
37+
plugins: [
38+
SwaggerUIBundle.plugins.DownloadUrl
39+
],
40+
layout: "StandaloneLayout",
41+
validatorUrl: null
42+
});
43+
};
44+
</script>
45+
</body>
46+
</html>

0 commit comments

Comments
 (0)