From a5bf4ee76cb3adbfcef0cb1d443f1595c7c7faae Mon Sep 17 00:00:00 2001 From: Mohamed Date: Mon, 3 Mar 2025 03:28:36 +0100 Subject: [PATCH] feat(ws): add swagger api docs to backend (#206) * Add Swagger Config Signed-off-by: mohamed-ben-khemis * Removed make watch Signed-off-by: mohamed-ben-khemis * add swag command Signed-off-by: mohamed-ben-khemis * Updated swagger output Signed-off-by: mohamed-ben-khemis * Serve YAML API spec alongside Swagger UI Signed-off-by: mohamed-ben-khemis * Updated general annotations Signed-off-by: mohamed-ben-khemis * Updated swagger docs version Signed-off-by: mohamed-ben-khemis * updated swagger config Signed-off-by: mohamed-ben-khemis * add parseDependency to swag init Signed-off-by: mohamed-ben-khemis * update http-swagger and factor handler out Signed-off-by: Mathew Wicks <5735406+thesuperzapper@users.noreply.github.com> * add swagger api path to readme Signed-off-by: Mathew Wicks <5735406+thesuperzapper@users.noreply.github.com> * regen swagger for camelCase change Signed-off-by: Mathew Wicks <5735406+thesuperzapper@users.noreply.github.com> * fix docstrings Signed-off-by: Mathew Wicks <5735406+thesuperzapper@users.noreply.github.com> --------- Signed-off-by: mohamed-ben-khemis Signed-off-by: Mathew Wicks <5735406+thesuperzapper@users.noreply.github.com> Co-authored-by: Mathew Wicks <5735406+thesuperzapper@users.noreply.github.com> --- workspaces/backend/Makefile | 25 ++- workspaces/backend/README.md | 1 + workspaces/backend/api/app.go | 8 + workspaces/backend/api/healthcheck_handler.go | 11 ++ workspaces/backend/api/swagger_handler.go | 33 ++++ workspaces/backend/cmd/main.go | 15 ++ workspaces/backend/go.mod | 25 ++- workspaces/backend/go.sum | 63 +++---- workspaces/backend/openapi/docs.go | 173 ++++++++++++++++++ workspaces/backend/openapi/swagger.json | 153 ++++++++++++++++ workspaces/backend/openapi/swagger.yaml | 109 +++++++++++ 11 files changed, 571 insertions(+), 45 deletions(-) create mode 100644 workspaces/backend/api/swagger_handler.go create mode 100644 workspaces/backend/openapi/docs.go create mode 100644 workspaces/backend/openapi/swagger.json create mode 100644 workspaces/backend/openapi/swagger.yaml diff --git a/workspaces/backend/Makefile b/workspaces/backend/Makefile index a5fad75b..959dbe3d 100644 --- a/workspaces/backend/Makefile +++ b/workspaces/backend/Makefile @@ -66,14 +66,24 @@ lint: golangci-lint ## Run golangci-lint linter lint-fix: golangci-lint ## Run golangci-lint linter and perform fixes $(GOLANGCI_LINT) run --fix +##@ Swagger +ALL_GO_DIRS := $(shell find . -type f -name '*.go' -exec dirname {} \; | sed 's|^\./||' | sort -u) +ALL_GO_DIRS_NO_CMD := $(shell echo "$(ALL_GO_DIRS)" | tr ' ' '\n' | grep -v '^cmd$$' | paste -sd, -) +SWAG_DIRS := cmd,$(ALL_GO_DIRS_NO_CMD) + +.PHONY: swag +swag: SWAGGER + $(SWAGGER) fmt -g main.go -d $(SWAG_DIRS) + $(SWAGGER) init --parseDependency -q -g main.go -d $(SWAG_DIRS) --output openapi + ##@ Build .PHONY: build -build: fmt vet ## Build backend binary. +build: fmt vet swag ## Build backend binary. go build -o bin/backend cmd/main.go -.PHONY: run -run: fmt vet ## Run a backend from your host. +.PHONY: run +run: fmt vet swag ## Run a backend from your host. go run ./cmd/main.go --port=$(PORT) # If you wish to build the manager image targeting other platforms you can use the --platform flag. @@ -115,10 +125,17 @@ $(LOCALBIN): KUBECTL ?= kubectl ENVTEST ?= $(LOCALBIN)/setup-envtest GOLANGCI_LINT = $(LOCALBIN)/golangci-lint +SWAGGER = $(LOCALBIN)/swag ## Tool Versions ENVTEST_VERSION ?= release-0.19 GOLANGCI_LINT_VERSION ?= v1.61.0 +SWAGGER_VERSION ?= v1.16.4 + +.PHONY: SWAGGER +SWAGGER: $(SWAGGER) +$(SWAGGER): $(LOCALBIN) + $(call go-install-tool,$(SWAGGER),github.com/swaggo/swag/cmd/swag,$(SWAGGER_VERSION)) .PHONY: envtest envtest: $(ENVTEST) ## Download setup-envtest locally if necessary. @@ -144,4 +161,4 @@ GOBIN=$(LOCALBIN) go install $${package} ;\ mv $(1) $(1)-$(3) ;\ } ;\ ln -sf $(1)-$(3) $(1) -endef +endef \ No newline at end of file diff --git a/workspaces/backend/README.md b/workspaces/backend/README.md index 04015d1f..f5cbd683 100644 --- a/workspaces/backend/README.md +++ b/workspaces/backend/README.md @@ -36,6 +36,7 @@ make run PORT=8000 |----------------------------------------------|------------------------|-----------------------------------------| | GET /api/v1/healthcheck | healthcheck_handler | Show application information | | GET /api/v1/namespaces | namespaces_handler | Get all Namespaces | +| GET /api/v1/swagger/ | swagger_handler | Swagger API documentation | | GET /api/v1/workspaces | workspaces_handler | Get all Workspaces | | GET /api/v1/workspaces/{namespace} | workspaces_handler | Get all Workspaces from a namespace | | POST /api/v1/workspaces/{namespace} | workspaces_handler | Create a Workspace in a given namespace | diff --git a/workspaces/backend/api/app.go b/workspaces/backend/api/app.go index 5e5dc233..ef3fe7db 100644 --- a/workspaces/backend/api/app.go +++ b/workspaces/backend/api/app.go @@ -28,6 +28,7 @@ import ( "github.com/kubeflow/notebooks/workspaces/backend/internal/config" "github.com/kubeflow/notebooks/workspaces/backend/internal/repositories" + _ "github.com/kubeflow/notebooks/workspaces/backend/openapi" ) const ( @@ -51,6 +52,10 @@ const ( // namespaces AllNamespacesPath = PathPrefix + "/namespaces" + + // swagger + SwaggerPath = PathPrefix + "/swagger/*any" + SwaggerDocPath = PathPrefix + "/swagger/doc.json" ) type App struct { @@ -102,5 +107,8 @@ func (a *App) Routes() http.Handler { router.GET(AllWorkspaceKindsPath, a.GetWorkspaceKindsHandler) router.GET(WorkspaceKindsByNamePath, a.GetWorkspaceKindHandler) + // swagger + router.GET(SwaggerPath, a.GetSwaggerHandler) + return a.recoverPanic(a.enableCORS(router)) } diff --git a/workspaces/backend/api/healthcheck_handler.go b/workspaces/backend/api/healthcheck_handler.go index dd61673e..69a1b78a 100644 --- a/workspaces/backend/api/healthcheck_handler.go +++ b/workspaces/backend/api/healthcheck_handler.go @@ -20,8 +20,19 @@ import ( "net/http" "github.com/julienschmidt/httprouter" + + _ "github.com/kubeflow/notebooks/workspaces/backend/internal/models/health_check" ) +// GetHealthcheckHandler returns the health status of the application. +// +// @Summary Returns the health status of the application +// @Description Provides a healthcheck response indicating the status of key services. +// @Tags healthcheck +// @Produce application/json +// @Success 200 {object} health_check.HealthCheck "Successful healthcheck response" +// @Failure 500 {object} ErrorEnvelope "Internal server error" +// @Router /healthcheck [get] func (a *App) GetHealthcheckHandler(w http.ResponseWriter, r *http.Request, _ httprouter.Params) { healthCheck, err := a.repositories.HealthCheck.HealthCheck(Version) diff --git a/workspaces/backend/api/swagger_handler.go b/workspaces/backend/api/swagger_handler.go new file mode 100644 index 00000000..1725af4b --- /dev/null +++ b/workspaces/backend/api/swagger_handler.go @@ -0,0 +1,33 @@ +/* +Copyright 2024. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package api + +import ( + "net/http" + + "github.com/julienschmidt/httprouter" + httpSwagger "github.com/swaggo/http-swagger/v2" +) + +func (a *App) GetSwaggerHandler(w http.ResponseWriter, r *http.Request, _ httprouter.Params) { + httpSwagger.Handler( + httpSwagger.URL(SwaggerDocPath), + httpSwagger.DeepLinking(true), + httpSwagger.DocExpansion("list"), + httpSwagger.DomID("swagger-ui"), + ).ServeHTTP(w, r) +} diff --git a/workspaces/backend/cmd/main.go b/workspaces/backend/cmd/main.go index 9b07c306..cbce9f63 100644 --- a/workspaces/backend/cmd/main.go +++ b/workspaces/backend/cmd/main.go @@ -32,6 +32,21 @@ import ( "github.com/kubeflow/notebooks/workspaces/backend/internal/server" ) +// @title Kubeflow Notebooks API +// @version 1.0.0 +// @description This API provides endpoints to manage notebooks in a Kubernetes cluster. +// @description For more information, visit https://www.kubeflow.org/docs/components/notebooks/ + +// @license.name Apache 2.0 +// @license.url http://www.apache.org/licenses/LICENSE-2.0.html + +// @host localhost:4000 +// @BasePath /api/v1 + +// @schemes http https +// @consumes application/json +// @produces application/json + func main() { // Define command line flags cfg := &config.EnvConfig{} diff --git a/workspaces/backend/go.mod b/workspaces/backend/go.mod index b459b779..ab546a80 100644 --- a/workspaces/backend/go.mod +++ b/workspaces/backend/go.mod @@ -9,6 +9,8 @@ require ( github.com/kubeflow/notebooks/workspaces/controller v0.0.0 github.com/onsi/ginkgo/v2 v2.19.0 github.com/onsi/gomega v1.33.1 + github.com/swaggo/http-swagger/v2 v2.0.2 + github.com/swaggo/swag v1.16.4 k8s.io/api v0.31.0 k8s.io/apimachinery v0.31.0 k8s.io/apiserver v0.31.0 @@ -18,6 +20,7 @@ require ( ) require ( + github.com/KyleBanks/depth v1.2.1 // indirect github.com/antlr4-go/antlr/v4 v4.13.0 // indirect github.com/asaskevich/govalidator v0.0.0-20190424111038-f61b66f89f4a // indirect github.com/beorn7/perks v1.0.1 // indirect @@ -33,9 +36,10 @@ require ( github.com/go-logr/logr v1.4.2 // indirect github.com/go-logr/stdr v1.2.2 // indirect github.com/go-logr/zapr v1.3.0 // indirect - github.com/go-openapi/jsonpointer v0.19.6 // indirect - github.com/go-openapi/jsonreference v0.20.2 // indirect - github.com/go-openapi/swag v0.22.4 // indirect + github.com/go-openapi/jsonpointer v0.21.0 // indirect + github.com/go-openapi/jsonreference v0.21.0 // indirect + github.com/go-openapi/spec v0.21.0 // indirect + github.com/go-openapi/swag v0.23.0 // indirect github.com/go-task/slim-sprig/v3 v3.0.0 // indirect github.com/gogo/protobuf v1.3.2 // indirect github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect @@ -51,7 +55,7 @@ require ( github.com/inconshreveable/mousetrap v1.1.0 // indirect github.com/josharian/intern v1.0.0 // indirect github.com/json-iterator/go v1.1.12 // indirect - github.com/mailru/easyjson v0.7.7 // indirect + github.com/mailru/easyjson v0.9.0 // indirect github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect github.com/modern-go/reflect2 v1.0.2 // indirect github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect @@ -63,6 +67,7 @@ require ( github.com/spf13/cobra v1.8.1 // indirect github.com/spf13/pflag v1.0.5 // indirect github.com/stoewer/go-strcase v1.2.0 // indirect + github.com/swaggo/files/v2 v2.0.2 // indirect github.com/x448/float16 v0.8.4 // indirect go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.53.0 // indirect go.opentelemetry.io/otel v1.28.0 // indirect @@ -75,14 +80,14 @@ require ( go.uber.org/multierr v1.11.0 // indirect go.uber.org/zap v1.26.0 // indirect golang.org/x/exp v0.0.0-20230515195305-f3d0a9c9a5cc // indirect - golang.org/x/net v0.26.0 // indirect + golang.org/x/net v0.35.0 // indirect golang.org/x/oauth2 v0.21.0 // indirect - golang.org/x/sync v0.7.0 // indirect - golang.org/x/sys v0.21.0 // indirect - golang.org/x/term v0.21.0 // indirect - golang.org/x/text v0.16.0 // indirect + golang.org/x/sync v0.11.0 // indirect + golang.org/x/sys v0.30.0 // indirect + golang.org/x/term v0.29.0 // indirect + golang.org/x/text v0.22.0 // indirect golang.org/x/time v0.3.0 // indirect - golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d // indirect + golang.org/x/tools v0.30.0 // indirect gomodules.xyz/jsonpatch/v2 v2.4.0 // indirect google.golang.org/genproto/googleapis/api v0.0.0-20240528184218-531527333157 // indirect google.golang.org/genproto/googleapis/rpc v0.0.0-20240701130421-f6361c86f094 // indirect diff --git a/workspaces/backend/go.sum b/workspaces/backend/go.sum index e2470d9c..4e67123c 100644 --- a/workspaces/backend/go.sum +++ b/workspaces/backend/go.sum @@ -1,3 +1,5 @@ +github.com/KyleBanks/depth v1.2.1 h1:5h8fQADFrWtarTdtDudMmGsC7GPbOAu6RVB3ffsVFHc= +github.com/KyleBanks/depth v1.2.1/go.mod h1:jzSb9d0L43HxTQfT+oSA1EEp2q+ne2uh6XgeJcm8brE= github.com/antlr4-go/antlr/v4 v4.13.0 h1:lxCg3LAv+EUK6t1i0y1V6/SLeUi0eKEKdhQAlS8TVTI= github.com/antlr4-go/antlr/v4 v4.13.0/go.mod h1:pfChB/xh/Unjila75QW7+VU4TSnWnnk9UTnmpPaOR2g= github.com/asaskevich/govalidator v0.0.0-20190424111038-f61b66f89f4a h1:idn718Q4B6AGu/h5Sxe66HYVdqdGu2l9Iebqhi/AEoA= @@ -11,7 +13,6 @@ github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyY github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs= github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs= github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= -github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM= @@ -35,13 +36,14 @@ github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag= github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE= github.com/go-logr/zapr v1.3.0 h1:XGdV8XW8zdwFiwOA2Dryh1gj2KRQyOOoNmBy4EplIcQ= github.com/go-logr/zapr v1.3.0/go.mod h1:YKepepNBd1u/oyhd/yQmtjVXmm9uML4IXUgMOwR8/Gg= -github.com/go-openapi/jsonpointer v0.19.6 h1:eCs3fxoIi3Wh6vtgmLTOjdhSpiqphQ+DaPn38N2ZdrE= -github.com/go-openapi/jsonpointer v0.19.6/go.mod h1:osyAmYz/mB/C3I+WsTTSgw1ONzaLJoLCyoi6/zppojs= -github.com/go-openapi/jsonreference v0.20.2 h1:3sVjiK66+uXK/6oQ8xgcRKcFgQ5KXa2KvnJRumpMGbE= -github.com/go-openapi/jsonreference v0.20.2/go.mod h1:Bl1zwGIM8/wsvqjsOQLJ/SH+En5Ap4rVB5KVcIDZG2k= -github.com/go-openapi/swag v0.22.3/go.mod h1:UzaqsxGiab7freDnrUUra0MwWfN/q7tE4j+VcZ0yl14= -github.com/go-openapi/swag v0.22.4 h1:QLMzNJnMGPRNDCbySlcj1x01tzU8/9LTTL9hZZZogBU= -github.com/go-openapi/swag v0.22.4/go.mod h1:UzaqsxGiab7freDnrUUra0MwWfN/q7tE4j+VcZ0yl14= +github.com/go-openapi/jsonpointer v0.21.0 h1:YgdVicSA9vH5RiHs9TZW5oyafXZFc6+2Vc1rr/O9oNQ= +github.com/go-openapi/jsonpointer v0.21.0/go.mod h1:IUyH9l/+uyhIYQ/PXVA41Rexl+kOkAPDdXEYns6fzUY= +github.com/go-openapi/jsonreference v0.21.0 h1:Rs+Y7hSXT83Jacb7kFyjn4ijOuVGSvOdF2+tg1TRrwQ= +github.com/go-openapi/jsonreference v0.21.0/go.mod h1:LmZmgsrTkVg9LG4EaHeY8cBDslNPMo06cago5JNLkm4= +github.com/go-openapi/spec v0.21.0 h1:LTVzPc3p/RzRnkQqLRndbAzjY0d0BCL72A6j3CdL9ZY= +github.com/go-openapi/spec v0.21.0/go.mod h1:78u6VdPw81XU44qEWGhtr982gJ5BWg2c0I5XwVMotYk= +github.com/go-openapi/swag v0.23.0 h1:vsEVJDUo2hPJ2tu0/Xc+4noaxyEffXNIs3cOULZ+GrE= +github.com/go-openapi/swag v0.23.0/go.mod h1:esZ8ITTYEsH1V2trKHjAN8Ai7xHb8RV+YSZ577vPjgQ= github.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1vB6EwHI= github.com/go-task/slim-sprig/v3 v3.0.0/go.mod h1:W848ghGpv3Qj3dhTPRyJypKRiqCdHZiAzKg9hl15HA8= github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q= @@ -78,15 +80,12 @@ github.com/julienschmidt/httprouter v1.3.0 h1:U0609e9tgbseu3rBINet9P48AI/D3oJs4d github.com/julienschmidt/httprouter v1.3.0/go.mod h1:JR6WtHb+2LUe8TCKY3cZOxFyyO8IZAc4RVcycCCAKdM= github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8= github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck= -github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI= github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE= github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk= -github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ= -github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI= github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= -github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0= -github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= +github.com/mailru/easyjson v0.9.0 h1:PrnmzHw7262yW8sTBwxi1PdJA3Iw/EKBa8psRf7d9a4= +github.com/mailru/easyjson v0.9.0/go.mod h1:1+xMtQp2MRNVL/V1bOzuP3aP8VNwRW55fQUto+XFtTU= github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q= github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg= github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q= @@ -121,15 +120,16 @@ github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An github.com/stoewer/go-strcase v1.2.0 h1:Z2iHWqGXH00XYgqDmNgQbIBxf3wrNq0F3feEy0ainaU= github.com/stoewer/go-strcase v1.2.0/go.mod h1:IBiWB2sKIp3wVVQ3Y035++gc+knqhUQag1KpM8ahLw8= github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= -github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw= -github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo= github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA= -github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= -github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU= -github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4= github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg= github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= +github.com/swaggo/files/v2 v2.0.2 h1:Bq4tgS/yxLB/3nwOMcul5oLEUKa877Ykgz3CJMVbQKU= +github.com/swaggo/files/v2 v2.0.2/go.mod h1:TVqetIzZsO9OhHX1Am9sRf9LdrFZqoK49N37KON/jr0= +github.com/swaggo/http-swagger/v2 v2.0.2 h1:FKCdLsl+sFCx60KFsyM0rDarwiUSZ8DqbfSyIKC9OBg= +github.com/swaggo/http-swagger/v2 v2.0.2/go.mod h1:r7/GBkAWIfK6E/OLnE8fXnviHiDeAHmgIyooa4xm3AQ= +github.com/swaggo/swag v1.16.4 h1:clWJtd9LStiG3VeijiCfOVODP6VpHtKdQy9ELFG3s1A= +github.com/swaggo/swag v1.16.4/go.mod h1:VBsHJRsDvfYvqoiMKnsdwhNV9LEMHgEDZcyVYX0sxPg= github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM= github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg= github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74= @@ -163,38 +163,40 @@ golang.org/x/exp v0.0.0-20230515195305-f3d0a9c9a5cc h1:mCRnTeVUjcrhlRmO0VK8a6k6R golang.org/x/exp v0.0.0-20230515195305-f3d0a9c9a5cc/go.mod h1:V1LtkGg67GoY2N1AnLN78QLrzxkLyJw7RJb1gzOOz9w= golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA= golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA= +golang.org/x/mod v0.23.0 h1:Zb7khfcRGKk+kqfxFaP5tZqCnDZMjC5VtUBs87Hr6QM= +golang.org/x/mod v0.23.0/go.mod h1:6SkKJ3Xj0I0BrPOZoBy3bdMptDDU9oJrpohJ3eWZ1fY= golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg= golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s= golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s= golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU= -golang.org/x/net v0.26.0 h1:soB7SVo0PWrY4vPW/+ay0jKDNScG2X9wFeYlXIvJsOQ= -golang.org/x/net v0.26.0/go.mod h1:5YKkiSynbBIh3p6iOc/vibscux0x38BZDkn8sCUPxHE= +golang.org/x/net v0.35.0 h1:T5GQRQb2y08kTAByq9L4/bz8cipCdA8FbRTXewonqY8= +golang.org/x/net v0.35.0/go.mod h1:EglIi67kWsHKlRzzVMUD93VMSWGFOMSZgxFjparz1Qk= golang.org/x/oauth2 v0.21.0 h1:tsimM75w1tF/uws5rbeHzIWxEqElMehnc+iW793zsZs= golang.org/x/oauth2 v0.21.0/go.mod h1:XYTD2NtWslqkgxebSiOHnXEap4TF09sJSc7H1sXbhtI= golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= -golang.org/x/sync v0.7.0 h1:YsImfSBoP9QPYL0xyKJPq0gcaJdG3rInoqxTWbfQu9M= -golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= +golang.org/x/sync v0.11.0 h1:GGz8+XQP4FvTTrjZPzNKTMFtSXH80RAzG+5ghFPgK9w= +golang.org/x/sync v0.11.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= -golang.org/x/sys v0.21.0 h1:rF+pYz3DAGSQAxAu1CbC7catZg4ebC4UIeIhKxBZvws= -golang.org/x/sys v0.21.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= -golang.org/x/term v0.21.0 h1:WVXCp+/EBEHOj53Rvu+7KiT/iElMrO8ACK16SMZ3jaA= -golang.org/x/term v0.21.0/go.mod h1:ooXLefLobQVslOqselCNF4SxFAaoS6KujMbsGzSDmX0= +golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc= +golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= +golang.org/x/term v0.29.0 h1:L6pJp37ocefwRRtYPKSWOWzOtWSxVajvz2ldH/xi3iU= +golang.org/x/term v0.29.0/go.mod h1:6bl4lRlvVuDgSf3179VpIxBF0o10JUpXWOnI7nErv7s= golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= -golang.org/x/text v0.16.0 h1:a94ExnEXNtEwYLGJSIUxnWoxoRz/ZcCsV63ROupILh4= -golang.org/x/text v0.16.0/go.mod h1:GhwF1Be+LQoKShO3cGOHzqOgRrGaYc9AvblQOmPVHnI= +golang.org/x/text v0.22.0 h1:bofq7m3/HAFvbF51jz3Q9wLg3jkvSPuiZu/pD1XwgtM= +golang.org/x/text v0.22.0/go.mod h1:YRoo4H8PVmsu+E3Ou7cqLVH8oXWIHVoX0jqUWALQhfY= golang.org/x/time v0.3.0 h1:rg5rLMjNzMS1RkNLzCG38eapWhnYLFYXDXj2gOlr8j4= golang.org/x/time v0.3.0/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ= golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE= golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA= -golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d h1:vU5i/LfpvrRCpgM/VPfJLg5KjxD3E+hfT1SH+d9zLwg= -golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk= +golang.org/x/tools v0.30.0 h1:BgcpHewrV5AUp2G9MebG4XPFI1E2W41zU1SaqVA9vJY= +golang.org/x/tools v0.30.0/go.mod h1:c347cR/OJfw5TI+GfX7RUPNMdDRRbjvYTS0jPyvsVtY= golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= @@ -220,7 +222,6 @@ gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= -gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= k8s.io/api v0.31.0 h1:b9LiSjR2ym/SzTOlfMHm1tr7/21aD7fSkqgD/CVJBCo= diff --git a/workspaces/backend/openapi/docs.go b/workspaces/backend/openapi/docs.go new file mode 100644 index 00000000..c16957b2 --- /dev/null +++ b/workspaces/backend/openapi/docs.go @@ -0,0 +1,173 @@ +// Package openapi Code generated by swaggo/swag. DO NOT EDIT +package openapi + +import "github.com/swaggo/swag" + +const docTemplate = `{ + "schemes": {{ marshal .Schemes }}, + "swagger": "2.0", + "info": { + "description": "{{escape .Description}}", + "title": "{{.Title}}", + "contact": {}, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + }, + "version": "{{.Version}}" + }, + "host": "{{.Host}}", + "basePath": "{{.BasePath}}", + "paths": { + "/healthcheck": { + "get": { + "description": "Provides a healthcheck response indicating the status of key services.", + "produces": [ + "application/json" + ], + "tags": [ + "healthcheck" + ], + "summary": "Returns the health status of the application", + "responses": { + "200": { + "description": "Successful healthcheck response", + "schema": { + "$ref": "#/definitions/health_check.HealthCheck" + } + }, + "500": { + "description": "Internal server error", + "schema": { + "$ref": "#/definitions/api.ErrorEnvelope" + } + } + } + } + } + }, + "definitions": { + "api.ErrorCause": { + "type": "object", + "properties": { + "validation_errors": { + "type": "array", + "items": { + "$ref": "#/definitions/api.ValidationError" + } + } + } + }, + "api.ErrorEnvelope": { + "type": "object", + "properties": { + "error": { + "$ref": "#/definitions/api.HTTPError" + } + } + }, + "api.HTTPError": { + "type": "object", + "properties": { + "cause": { + "$ref": "#/definitions/api.ErrorCause" + }, + "code": { + "type": "string" + }, + "message": { + "type": "string" + } + } + }, + "api.ValidationError": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "type": { + "$ref": "#/definitions/field.ErrorType" + } + } + }, + "field.ErrorType": { + "type": "string", + "enum": [ + "FieldValueNotFound", + "FieldValueRequired", + "FieldValueDuplicate", + "FieldValueInvalid", + "FieldValueNotSupported", + "FieldValueForbidden", + "FieldValueTooLong", + "FieldValueTooMany", + "InternalError", + "FieldValueTypeInvalid" + ], + "x-enum-varnames": [ + "ErrorTypeNotFound", + "ErrorTypeRequired", + "ErrorTypeDuplicate", + "ErrorTypeInvalid", + "ErrorTypeNotSupported", + "ErrorTypeForbidden", + "ErrorTypeTooLong", + "ErrorTypeTooMany", + "ErrorTypeInternal", + "ErrorTypeTypeInvalid" + ] + }, + "health_check.HealthCheck": { + "type": "object", + "properties": { + "status": { + "$ref": "#/definitions/health_check.ServiceStatus" + }, + "systemInfo": { + "$ref": "#/definitions/health_check.SystemInfo" + } + } + }, + "health_check.ServiceStatus": { + "type": "string", + "enum": [ + "Healthy", + "Unhealthy" + ], + "x-enum-varnames": [ + "ServiceStatusHealthy", + "ServiceStatusUnhealthy" + ] + }, + "health_check.SystemInfo": { + "type": "object", + "properties": { + "version": { + "type": "string" + } + } + } + } +}` + +// SwaggerInfo holds exported Swagger Info so clients can modify it +var SwaggerInfo = &swag.Spec{ + Version: "1.0.0", + Host: "localhost:4000", + BasePath: "/api/v1", + Schemes: []string{"http", "https"}, + Title: "Kubeflow Notebooks API", + Description: "This API provides endpoints to manage notebooks in a Kubernetes cluster.\nFor more information, visit https://www.kubeflow.org/docs/components/notebooks/", + InfoInstanceName: "swagger", + SwaggerTemplate: docTemplate, + LeftDelim: "{{", + RightDelim: "}}", +} + +func init() { + swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo) +} diff --git a/workspaces/backend/openapi/swagger.json b/workspaces/backend/openapi/swagger.json new file mode 100644 index 00000000..50644d14 --- /dev/null +++ b/workspaces/backend/openapi/swagger.json @@ -0,0 +1,153 @@ +{ + "schemes": [ + "http", + "https" + ], + "swagger": "2.0", + "info": { + "description": "This API provides endpoints to manage notebooks in a Kubernetes cluster.\nFor more information, visit https://www.kubeflow.org/docs/components/notebooks/", + "title": "Kubeflow Notebooks API", + "contact": {}, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + }, + "version": "1.0.0" + }, + "host": "localhost:4000", + "basePath": "/api/v1", + "paths": { + "/healthcheck": { + "get": { + "description": "Provides a healthcheck response indicating the status of key services.", + "produces": [ + "application/json" + ], + "tags": [ + "healthcheck" + ], + "summary": "Returns the health status of the application", + "responses": { + "200": { + "description": "Successful healthcheck response", + "schema": { + "$ref": "#/definitions/health_check.HealthCheck" + } + }, + "500": { + "description": "Internal server error", + "schema": { + "$ref": "#/definitions/api.ErrorEnvelope" + } + } + } + } + } + }, + "definitions": { + "api.ErrorCause": { + "type": "object", + "properties": { + "validation_errors": { + "type": "array", + "items": { + "$ref": "#/definitions/api.ValidationError" + } + } + } + }, + "api.ErrorEnvelope": { + "type": "object", + "properties": { + "error": { + "$ref": "#/definitions/api.HTTPError" + } + } + }, + "api.HTTPError": { + "type": "object", + "properties": { + "cause": { + "$ref": "#/definitions/api.ErrorCause" + }, + "code": { + "type": "string" + }, + "message": { + "type": "string" + } + } + }, + "api.ValidationError": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "type": { + "$ref": "#/definitions/field.ErrorType" + } + } + }, + "field.ErrorType": { + "type": "string", + "enum": [ + "FieldValueNotFound", + "FieldValueRequired", + "FieldValueDuplicate", + "FieldValueInvalid", + "FieldValueNotSupported", + "FieldValueForbidden", + "FieldValueTooLong", + "FieldValueTooMany", + "InternalError", + "FieldValueTypeInvalid" + ], + "x-enum-varnames": [ + "ErrorTypeNotFound", + "ErrorTypeRequired", + "ErrorTypeDuplicate", + "ErrorTypeInvalid", + "ErrorTypeNotSupported", + "ErrorTypeForbidden", + "ErrorTypeTooLong", + "ErrorTypeTooMany", + "ErrorTypeInternal", + "ErrorTypeTypeInvalid" + ] + }, + "health_check.HealthCheck": { + "type": "object", + "properties": { + "status": { + "$ref": "#/definitions/health_check.ServiceStatus" + }, + "systemInfo": { + "$ref": "#/definitions/health_check.SystemInfo" + } + } + }, + "health_check.ServiceStatus": { + "type": "string", + "enum": [ + "Healthy", + "Unhealthy" + ], + "x-enum-varnames": [ + "ServiceStatusHealthy", + "ServiceStatusUnhealthy" + ] + }, + "health_check.SystemInfo": { + "type": "object", + "properties": { + "version": { + "type": "string" + } + } + } + } +} \ No newline at end of file diff --git a/workspaces/backend/openapi/swagger.yaml b/workspaces/backend/openapi/swagger.yaml new file mode 100644 index 00000000..89027d92 --- /dev/null +++ b/workspaces/backend/openapi/swagger.yaml @@ -0,0 +1,109 @@ +basePath: /api/v1 +definitions: + api.ErrorCause: + properties: + validation_errors: + items: + $ref: '#/definitions/api.ValidationError' + type: array + type: object + api.ErrorEnvelope: + properties: + error: + $ref: '#/definitions/api.HTTPError' + type: object + api.HTTPError: + properties: + cause: + $ref: '#/definitions/api.ErrorCause' + code: + type: string + message: + type: string + type: object + api.ValidationError: + properties: + field: + type: string + message: + type: string + type: + $ref: '#/definitions/field.ErrorType' + type: object + field.ErrorType: + enum: + - FieldValueNotFound + - FieldValueRequired + - FieldValueDuplicate + - FieldValueInvalid + - FieldValueNotSupported + - FieldValueForbidden + - FieldValueTooLong + - FieldValueTooMany + - InternalError + - FieldValueTypeInvalid + type: string + x-enum-varnames: + - ErrorTypeNotFound + - ErrorTypeRequired + - ErrorTypeDuplicate + - ErrorTypeInvalid + - ErrorTypeNotSupported + - ErrorTypeForbidden + - ErrorTypeTooLong + - ErrorTypeTooMany + - ErrorTypeInternal + - ErrorTypeTypeInvalid + health_check.HealthCheck: + properties: + status: + $ref: '#/definitions/health_check.ServiceStatus' + systemInfo: + $ref: '#/definitions/health_check.SystemInfo' + type: object + health_check.ServiceStatus: + enum: + - Healthy + - Unhealthy + type: string + x-enum-varnames: + - ServiceStatusHealthy + - ServiceStatusUnhealthy + health_check.SystemInfo: + properties: + version: + type: string + type: object +host: localhost:4000 +info: + contact: {} + description: |- + This API provides endpoints to manage notebooks in a Kubernetes cluster. + For more information, visit https://www.kubeflow.org/docs/components/notebooks/ + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html + title: Kubeflow Notebooks API + version: 1.0.0 +paths: + /healthcheck: + get: + description: Provides a healthcheck response indicating the status of key services. + produces: + - application/json + responses: + "200": + description: Successful healthcheck response + schema: + $ref: '#/definitions/health_check.HealthCheck' + "500": + description: Internal server error + schema: + $ref: '#/definitions/api.ErrorEnvelope' + summary: Returns the health status of the application + tags: + - healthcheck +schemes: +- http +- https +swagger: "2.0"