Skip to content

feat(ws): complete api swagger documentation across workspaces, namespaces, and workspacekinds #235

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 13 commits into
base: notebooks-v2
Choose a base branch
from
Open

feat(ws): complete api swagger documentation across workspaces, namespaces, and workspacekinds #235

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
04b28b5
Add Swagger Config
Mohamed-ben-khemis Feb 12, 2025
2933087
add swag command
Mohamed-ben-khemis Feb 12, 2025
852d1ea
Updated swagger output
Mohamed-ben-khemis Feb 13, 2025
1a27205
Updated general annotations
Mohamed-ben-khemis Feb 13, 2025
31e1ff6
Updated swagger docs version
Mohamed-ben-khemis Feb 13, 2025
aedf802
updated swagger config
Mohamed-ben-khemis Feb 19, 2025
06ee6ea
fix confilicts
Mohamed-ben-khemis Mar 17, 2025
2851835
Add GetNamespaces Swagger Docs
Mohamed-ben-khemis Mar 17, 2025
c687937
Add Workspaces Swagger Docs
Mohamed-ben-khemis Mar 17, 2025
7ac38a1
Add Workspaces Swagger Docs
Mohamed-ben-khemis Mar 17, 2025
dc5fc47
Add Workspacekinds Swagger Docs
Mohamed-ben-khemis Mar 17, 2025
684bc95
fix: prevent Swagger from reading TODO comment by adding a tab
Mohamed-ben-khemis Mar 17, 2025
8ad2d55
fix: resolve double api/v1 prefix in route paths
Mohamed-ben-khemis May 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions workspaces/backend/api/helpers.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ import (
// NOTE: error responses use the ErrorEnvelope type
type Envelope[D any] struct {
// TODO: make all declarations of Envelope use pointers for D

Data D `json:"data"`
}

Expand Down
11 changes: 11 additions & 0 deletions workspaces/backend/api/namespaces_handler.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,17 @@ import (

type NamespaceListEnvelope Envelope[[]models.Namespace]

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

// =========================== AUTH ===========================
Expand Down
29 changes: 29 additions & 0 deletions workspaces/backend/api/workspacekinds_handler.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,22 @@ type WorkspaceKindListEnvelope Envelope[[]models.WorkspaceKind]

type WorkspaceKindEnvelope Envelope[models.WorkspaceKind]

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

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

// GetWorkspaceKindsHandler returns a list of all available workspace kinds.
//
// @Summary List workspace kinds
// @Description Returns a list of all available workspace kinds. Workspace kinds define the different types of workspaces that can be created in the system.
// @Tags workspacekinds
// @Accept json
// @Produce json
// @Success 200 {object} WorkspaceKindListEnvelope "Successful operation. Returns a list of all available workspace kinds."
// @Failure 401 {object} ErrorEnvelope "Unauthorized. Authentication is required."
// @Failure 403 {object} ErrorEnvelope "Forbidden. User does not have permission to list workspace kinds."
// @Failure 500 {object} ErrorEnvelope "Internal server error. An unexpected error occurred on the server."
// @Router /workspacekinds [get]
// @Security ApiKeyAuth
func (a *App) GetWorkspaceKindsHandler(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
// =========================== AUTH ===========================
authPolicies := []*auth.ResourcePolicy{
Expand Down
69 changes: 69 additions & 0 deletions workspaces/backend/api/workspaces_handler.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,23 @@ type WorkspaceListEnvelope Envelope[[]models.Workspace]

type WorkspaceEnvelope Envelope[models.Workspace]

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

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

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

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

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

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