Skip to content

Commit b9c19ad

Browse files
andyatmiamiandyatmiami
committed
fix(ws): honor PORT in swagger UI and clean up backend README
This commit makes 2 improvements to our existing Swagger implementation in the `backend` component - overrides openapi.SwaggerInfo.Host at runtime to ensure the `PORT` value (which may have been overriden to != `4000`) is properly reflected in the generated Swagger HTML - Updates the `backend` `README.md` to instruct _the reader_ to run the `backend` application and visit the Swagger webpage to learn about the available APIs. - Removal of the markdown table and sample calls helps remove pointless developer toil and/or potential of stale/conflicting info as that information had to be manually maintained. Signed-off-by: Andy Stoneberg <[email protected]>
1 parent fb0e74a commit b9c19ad

File tree

2 files changed

+13
-116
lines changed

2 files changed

+13
-116
lines changed

‎workspaces/backend/README.md

Lines changed: 5 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -27,124 +27,14 @@ make run
2727
If you want to use a different port:
2828

2929
```shell
30-
make run PORT=8000
30+
make run PORT=8000
3131
```
3232

3333
### Endpoints
3434

35-
| URL Pattern | Handler | Action |
36-
|----------------------------------------------|------------------------|-----------------------------------------|
37-
| GET /api/v1/healthcheck | healthcheck_handler | Show application information |
38-
| GET /api/v1/namespaces | namespaces_handler | Get all Namespaces |
39-
| GET /api/v1/swagger/ | swagger_handler | Swagger API documentation |
40-
| GET /api/v1/workspaces | workspaces_handler | Get all Workspaces |
41-
| GET /api/v1/workspaces/{namespace} | workspaces_handler | Get all Workspaces from a namespace |
42-
| POST /api/v1/workspaces/{namespace} | workspaces_handler | Create a Workspace in a given namespace |
43-
| GET /api/v1/workspaces/{namespace}/{name} | workspaces_handler | Get a Workspace entity |
44-
| PATCH /api/v1/workspaces/{namespace}/{name} | TBD | Patch a Workspace entity |
45-
| PUT /api/v1/workspaces/{namespace}/{name} | TBD | Update a Workspace entity |
46-
| DELETE /api/v1/workspaces/{namespace}/{name} | workspaces_handler | Delete a Workspace entity |
47-
| GET /api/v1/workspacekinds | workspacekinds_handler | Get all WorkspaceKind |
48-
| POST /api/v1/workspacekinds | TBD | Create a WorkspaceKind |
49-
| GET /api/v1/workspacekinds/{name} | workspacekinds_handler | Get a WorkspaceKind entity |
50-
| PATCH /api/v1/workspacekinds/{name} | TBD | Patch a WorkspaceKind entity |
51-
| PUT /api/v1/workspacekinds/{name} | TBD | Update a WorkspaceKind entity |
52-
| DELETE /api/v1/workspacekinds/{name} | TBD | Delete a WorkspaceKind entity |
35+
The `backend` server exposes a Swagger UI typically available at localhost:4000/api/v1/swagger/index.html.
36+
- :warning: If providing a `PORT` override in `make run`, please ensure to use that port when composing the URL
5337

54-
### Sample local calls
38+
Running the `backend` to view the Swagger UI is the proper means to learning about and interact with the available APIs.
5539

56-
Healthcheck:
57-
58-
```shell
59-
# GET /api/v1/healthcheck
60-
curl -i localhost:4000/api/v1/healthcheck
61-
```
62-
63-
List all Namespaces:
64-
65-
```shell
66-
# GET /api/v1/namespaces
67-
curl -i localhost:4000/api/v1/namespaces
68-
```
69-
70-
List all Workspaces:
71-
72-
```shell
73-
# GET /api/v1/workspaces/
74-
curl -i localhost:4000/api/v1/workspaces
75-
```
76-
77-
List all Workspaces in a Namespace:
78-
79-
```shell
80-
# GET /api/v1/workspaces/{namespace}
81-
curl -i localhost:4000/api/v1/workspaces/default
82-
```
83-
84-
Create a Workspace:
85-
86-
```shell
87-
# POST /api/v1/workspaces/{namespace}
88-
curl -X POST http://localhost:4000/api/v1/workspaces/default \
89-
-H "Content-Type: application/json" \
90-
-d '{
91-
"data": {
92-
"name": "dora",
93-
"kind": "jupyterlab",
94-
"paused": false,
95-
"deferUpdates": false,
96-
"podTemplate": {
97-
"podMetadata": {
98-
"labels": {
99-
"app": "dora"
100-
},
101-
"annotations": {
102-
"app": "dora"
103-
}
104-
},
105-
"volumes": {
106-
"home": "workspace-home-bella",
107-
"data": [
108-
{
109-
"pvcName": "workspace-data-bella",
110-
"mountPath": "/data/my-data",
111-
"readOnly": false
112-
}
113-
]
114-
},
115-
"options": {
116-
"imageConfig": "jupyterlab_scipy_190",
117-
"podConfig": "tiny_cpu"
118-
}
119-
}
120-
}
121-
}'
122-
```
123-
124-
Get a Workspace:
125-
126-
```shell
127-
# GET /api/v1/workspaces/{namespace}/{name}
128-
curl -i localhost:4000/api/v1/workspaces/default/dora
129-
```
130-
131-
Delete a Workspace:
132-
133-
```shell
134-
# DELETE /api/v1/workspaces/{namespace}/{name}
135-
curl -X DELETE localhost:4000/api/v1/workspaces/default/dora
136-
```
137-
138-
List all WorkspaceKinds:
139-
140-
```shell
141-
# GET /api/v1/workspacekinds
142-
curl -i localhost:4000/api/v1/workspacekinds
143-
```
144-
145-
Get a WorkspaceKind:
146-
147-
```shell
148-
# GET /api/v1/workspacekinds/{name}
149-
curl -i localhost:4000/api/v1/workspacekinds/jupyterlab
150-
```
40+
If you wish to understand which handlers service the various endpoints, you can find the mapping in the `Routes()` function in [`app.go`](./api/app.go).

‎workspaces/backend/api/app.go

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,9 @@ package api
1919
import (
2020
"fmt"
2121
"log/slog"
22+
"net"
2223
"net/http"
24+
"strconv"
2325

2426
"github.com/julienschmidt/httprouter"
2527
"k8s.io/apimachinery/pkg/runtime"
@@ -30,7 +32,7 @@ import (
3032

3133
"github.com/kubeflow/notebooks/workspaces/backend/internal/config"
3234
"github.com/kubeflow/notebooks/workspaces/backend/internal/repositories"
33-
_ "github.com/kubeflow/notebooks/workspaces/backend/openapi"
35+
"github.com/kubeflow/notebooks/workspaces/backend/openapi"
3436
)
3537

3638
const (
@@ -78,6 +80,11 @@ func NewApp(cfg *config.EnvConfig, logger *slog.Logger, cl client.Client, scheme
7880

7981
// TODO: log the configuration on startup
8082

83+
// Override SwaggerInfo.Host with the correct port
84+
if host, _, err := net.SplitHostPort(openapi.SwaggerInfo.Host); err == nil {
85+
openapi.SwaggerInfo.Host = net.JoinHostPort(host, strconv.Itoa(cfg.Port))
86+
}
87+
8188
// get a serializer for Kubernetes YAML
8289
codecFactory := serializer.NewCodecFactory(scheme)
8390
yamlSerializerInfo, found := runtime.SerializerInfoForMediaType(codecFactory.SupportedMediaTypes(), runtime.ContentTypeYAML)

0 commit comments

Comments
 (0)