Skip to content

Commit 45d778a

Browse files
Mohamed-ben-khemisMohamed-ben-khemis
authored
feat(ws): complete api swagger documentation across workspaces, namespaces, and workspacekinds (#235)
* Add Swagger Config Signed-off-by: mohamed-ben-khemis <[email protected]> * add swag command Signed-off-by: mohamed-ben-khemis <[email protected]> * Updated swagger output Signed-off-by: mohamed-ben-khemis <[email protected]> * Updated general annotations Signed-off-by: mohamed-ben-khemis <[email protected]> * Updated swagger docs version Signed-off-by: mohamed-ben-khemis <[email protected]> * updated swagger config Signed-off-by: mohamed-ben-khemis <[email protected]> * fix confilicts Signed-off-by: mohamed-ben-khemis <[email protected]> * Add GetNamespaces Swagger Docs Signed-off-by: mohamed-ben-khemis <[email protected]> * Add Workspaces Swagger Docs Signed-off-by: mohamed-ben-khemis <[email protected]> * Add Workspaces Swagger Docs Signed-off-by: mohamed-ben-khemis <[email protected]> * Add Workspacekinds Swagger Docs Signed-off-by: mohamed-ben-khemis <[email protected]> * fix: prevent Swagger from reading TODO comment by adding a tab Signed-off-by: mohamed-ben-khemis <[email protected]> * fix: resolve double api/v1 prefix in route paths Signed-off-by: mohamed-ben-khemis <[email protected]> --------- Signed-off-by: mohamed-ben-khemis <[email protected]>
1 parent c81f412 commit 45d778a

File tree

7 files changed

+3377
-96
lines changed

7 files changed

+3377
-96
lines changed

‎workspaces/backend/api/helpers.go

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ import (
2828
// NOTE: error responses use the ErrorEnvelope type
2929
type Envelope[D any] struct {
3030
// TODO: make all declarations of Envelope use pointers for D
31+
3132
Data D `json:"data"`
3233
}
3334

‎workspaces/backend/api/namespaces_handler.go

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,17 @@ import (
2828

2929
type NamespaceListEnvelope Envelope[[]models.Namespace]
3030

31+
// GetNamespacesHandler returns a list of all namespaces.
32+
//
33+
// @Summary Returns a list of all namespaces
34+
// @Description Provides a list of all namespaces that the user has access to
35+
// @Tags namespaces
36+
// @Produce application/json
37+
// @Success 200 {object} NamespaceListEnvelope "Successful namespaces response"
38+
// @Failure 401 {object} ErrorEnvelope "Unauthorized"
39+
// @Failure 403 {object} ErrorEnvelope "Forbidden"
40+
// @Failure 500 {object} ErrorEnvelope "Internal server error"
41+
// @Router /namespaces [get]
3142
func (a *App) GetNamespacesHandler(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
3243

3344
// =========================== AUTH ===========================

‎workspaces/backend/api/workspacekinds_handler.go

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,22 @@ type WorkspaceKindListEnvelope Envelope[[]models.WorkspaceKind]
3535

3636
type WorkspaceKindEnvelope Envelope[models.WorkspaceKind]
3737

38+
// GetWorkspaceKindHandler retrieves a specific workspace kind by name.
39+
//
40+
// @Summary Get workspace kind
41+
// @Description Returns details of a specific workspace kind identified by its name. Workspace kinds define the available types of workspaces that can be created.
42+
// @Tags workspacekinds
43+
// @Accept json
44+
// @Produce json
45+
// @Param name path string true "Name of the workspace kind" example(jupyterlab)
46+
// @Success 200 {object} WorkspaceKindEnvelope "Successful operation. Returns the requested workspace kind details."
47+
// @Failure 400 {object} ErrorEnvelope "Bad Request. Invalid workspace kind name format."
48+
// @Failure 401 {object} ErrorEnvelope "Unauthorized. Authentication is required."
49+
// @Failure 403 {object} ErrorEnvelope "Forbidden. User does not have permission to access the workspace kind."
50+
// @Failure 404 {object} ErrorEnvelope "Not Found. Workspace kind does not exist."
51+
// @Failure 500 {object} ErrorEnvelope "Internal server error. An unexpected error occurred on the server."
52+
// @Router /workspacekinds/{name} [get]
53+
// @Security ApiKeyAuth
3854
func (a *App) GetWorkspaceKindHandler(w http.ResponseWriter, r *http.Request, ps httprouter.Params) {
3955
name := ps.ByName(ResourceNamePathParam)
4056

@@ -74,6 +90,19 @@ func (a *App) GetWorkspaceKindHandler(w http.ResponseWriter, r *http.Request, ps
7490
a.dataResponse(w, r, responseEnvelope)
7591
}
7692

93+
// GetWorkspaceKindsHandler returns a list of all available workspace kinds.
94+
//
95+
// @Summary List workspace kinds
96+
// @Description Returns a list of all available workspace kinds. Workspace kinds define the different types of workspaces that can be created in the system.
97+
// @Tags workspacekinds
98+
// @Accept json
99+
// @Produce json
100+
// @Success 200 {object} WorkspaceKindListEnvelope "Successful operation. Returns a list of all available workspace kinds."
101+
// @Failure 401 {object} ErrorEnvelope "Unauthorized. Authentication is required."
102+
// @Failure 403 {object} ErrorEnvelope "Forbidden. User does not have permission to list workspace kinds."
103+
// @Failure 500 {object} ErrorEnvelope "Internal server error. An unexpected error occurred on the server."
104+
// @Router /workspacekinds [get]
105+
// @Security ApiKeyAuth
77106
func (a *App) GetWorkspaceKindsHandler(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
78107
// =========================== AUTH ===========================
79108
authPolicies := []*auth.ResourcePolicy{

‎workspaces/backend/api/workspaces_handler.go

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,23 @@ type WorkspaceListEnvelope Envelope[[]models.Workspace]
3939

4040
type WorkspaceEnvelope Envelope[models.Workspace]
4141

42+
// GetWorkspaceHandler retrieves a specific workspace by namespace and name.
43+
//
44+
// @Summary Get workspace
45+
// @Description Returns details of a specific workspace identified by namespace and workspace name.
46+
// @Tags workspaces
47+
// @Accept json
48+
// @Produce json
49+
// @Param namespace path string true "Namespace of the workspace" example(kubeflow-user-example-com)
50+
// @Param workspace_name path string true "Name of the workspace" example(my-workspace)
51+
// @Success 200 {object} WorkspaceEnvelope "Successful operation. Returns the requested workspace details."
52+
// @Failure 400 {object} ErrorEnvelope "Bad Request. Invalid namespace or workspace name format."
53+
// @Failure 401 {object} ErrorEnvelope "Unauthorized. Authentication is required."
54+
// @Failure 403 {object} ErrorEnvelope "Forbidden. User does not have permission to access the workspace."
55+
// @Failure 404 {object} ErrorEnvelope "Not Found. Workspace does not exist."
56+
// @Failure 500 {object} ErrorEnvelope "Internal server error. An unexpected error occurred on the server."
57+
// @Router /workspaces/{namespace}/{workspace_name} [get]
58+
// @Security ApiKeyAuth
4259
func (a *App) GetWorkspaceHandler(w http.ResponseWriter, r *http.Request, ps httprouter.Params) {
4360
namespace := ps.ByName(NamespacePathParam)
4461
workspaceName := ps.ByName(ResourceNamePathParam)
@@ -83,6 +100,24 @@ func (a *App) GetWorkspaceHandler(w http.ResponseWriter, r *http.Request, ps htt
83100
a.dataResponse(w, r, responseEnvelope)
84101
}
85102

103+
// GetWorkspacesHandler returns a list of workspaces.
104+
//
105+
// @Summary List workspaces
106+
// @Description Returns a list of workspaces. The endpoint supports two modes:
107+
// @Description 1. List all workspaces across all namespaces (when no namespace is provided)
108+
// @Description 2. List workspaces in a specific namespace (when namespace is provided)
109+
// @Tags workspaces
110+
// @Accept json
111+
// @Produce json
112+
// @Param namespace path string false "Namespace to filter workspaces. If not provided, returns all workspaces across all namespaces." example(kubeflow-user-example-com)
113+
// @Success 200 {object} WorkspaceListEnvelope "Successful operation. Returns a list of workspaces."
114+
// @Failure 400 {object} ErrorEnvelope "Bad Request. Invalid namespace format."
115+
// @Failure 401 {object} ErrorEnvelope "Unauthorized. Authentication is required."
116+
// @Failure 403 {object} ErrorEnvelope "Forbidden. User does not have permission to list workspaces."
117+
// @Failure 500 {object} ErrorEnvelope "Internal server error. An unexpected error occurred on the server."
118+
// @Router /workspaces [get]
119+
// @Router /workspaces/{namespace} [get]
120+
// @Security ApiKeyAuth
86121
func (a *App) GetWorkspacesHandler(w http.ResponseWriter, r *http.Request, ps httprouter.Params) {
87122
namespace := ps.ByName(NamespacePathParam)
88123

@@ -129,6 +164,23 @@ func (a *App) GetWorkspacesHandler(w http.ResponseWriter, r *http.Request, ps ht
129164
a.dataResponse(w, r, responseEnvelope)
130165
}
131166

167+
// CreateWorkspaceHandler creates a new workspace in the specified namespace.
168+
//
169+
// @Summary Create workspace
170+
// @Description Creates a new workspace in the specified namespace.
171+
// @Tags workspaces
172+
// @Accept json
173+
// @Produce json
174+
// @Param namespace path string true "Namespace for the workspace" example(kubeflow-user-example-com)
175+
// @Param body body WorkspaceCreateEnvelope true "Workspace creation configuration"
176+
// @Success 201 {object} WorkspaceEnvelope "Workspace created successfully"
177+
// @Failure 400 {object} ErrorEnvelope "Bad Request. Invalid request body or namespace format."
178+
// @Failure 401 {object} ErrorEnvelope "Unauthorized. Authentication is required."
179+
// @Failure 403 {object} ErrorEnvelope "Forbidden. User does not have permission to create workspace."
180+
// @Failure 409 {object} ErrorEnvelope "Conflict. Workspace with the same name already exists."
181+
// @Failure 500 {object} ErrorEnvelope "Internal server error. An unexpected error occurred on the server."
182+
// @Router /workspaces/{namespace} [post]
183+
// @Security ApiKeyAuth
132184
func (a *App) CreateWorkspaceHandler(w http.ResponseWriter, r *http.Request, ps httprouter.Params) {
133185
namespace := ps.ByName(NamespacePathParam)
134186

@@ -207,6 +259,23 @@ func (a *App) CreateWorkspaceHandler(w http.ResponseWriter, r *http.Request, ps
207259
a.createdResponse(w, r, responseEnvelope, location)
208260
}
209261

262+
// DeleteWorkspaceHandler deletes a specific workspace by namespace and name.
263+
//
264+
// @Summary Delete workspace
265+
// @Description Deletes a specific workspace identified by namespace and workspace name.
266+
// @Tags workspaces
267+
// @Accept json
268+
// @Produce json
269+
// @Param namespace path string true "Namespace of the workspace" example(kubeflow-user-example-com)
270+
// @Param workspace_name path string true "Name of the workspace" example(my-workspace)
271+
// @Success 204 {object} nil "Workspace deleted successfully"
272+
// @Failure 400 {object} ErrorEnvelope "Bad Request. Invalid namespace or workspace name format."
273+
// @Failure 401 {object} ErrorEnvelope "Unauthorized. Authentication is required."
274+
// @Failure 403 {object} ErrorEnvelope "Forbidden. User does not have permission to delete the workspace."
275+
// @Failure 404 {object} ErrorEnvelope "Not Found. Workspace does not exist."
276+
// @Failure 500 {object} ErrorEnvelope "Internal server error. An unexpected error occurred on the server."
277+
// @Router /workspaces/{namespace}/{workspace_name} [delete]
278+
// @Security ApiKeyAuth
210279
func (a *App) DeleteWorkspaceHandler(w http.ResponseWriter, r *http.Request, ps httprouter.Params) {
211280
namespace := ps.ByName(NamespacePathParam)
212281
workspaceName := ps.ByName(ResourceNamePathParam)

0 commit comments

Comments
 (0)