feat(ws): add swagger api docs to backend (#206)

* Add Swagger Config Signed-off-by: mohamed-ben-khemis <mohamedbenkhemiswork576@gmail.com> * Removed make watch Signed-off-by: mohamed-ben-khemis <mohamedbenkhemiswork576@gmail.com> * add swag command Signed-off-by: mohamed-ben-khemis <mohamedbenkhemiswork576@gmail.com> * Updated swagger output Signed-off-by: mohamed-ben-khemis <mohamedbenkhemiswork576@gmail.com> * Serve YAML API spec alongside Swagger UI Signed-off-by: mohamed-ben-khemis <mohamedbenkhemiswork576@gmail.com> * Updated general annotations Signed-off-by: mohamed-ben-khemis <mohamedbenkhemiswork576@gmail.com> * Updated swagger docs version Signed-off-by: mohamed-ben-khemis <mohamedbenkhemiswork576@gmail.com> * updated swagger config Signed-off-by: mohamed-ben-khemis <mohamedbenkhemiswork576@gmail.com> * add parseDependency to swag init Signed-off-by: mohamed-ben-khemis <mohamedbenkhemiswork576@gmail.com> * 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 <mohamedbenkhemiswork576@gmail.com> Signed-off-by: Mathew Wicks <5735406+thesuperzapper@users.noreply.github.com> Co-authored-by: Mathew Wicks <5735406+thesuperzapper@users.noreply.github.com>
kubeflow · Mar 3, 2025 · a5bf4ee · a5bf4ee
1 parent 365c44b
commit a5bf4ee
Show file tree

Hide file tree

Showing 11 changed files with 571 additions and 45 deletions.
diff --git 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
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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