Skip to content

Commit a5bf4ee

Browse files
Mohamed-ben-khemisthesuperzapper
Mohamed-ben-khemis
and
thesuperzapper
authored
feat(ws): add swagger api docs to backend (#206)
* Add Swagger Config Signed-off-by: mohamed-ben-khemis <[email protected]> * Removed make watch 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]> * Serve YAML API spec alongside Swagger UI 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]> * add parseDependency to swag init Signed-off-by: mohamed-ben-khemis <[email protected]> * update http-swagger and factor handler out Signed-off-by: Mathew Wicks <[email protected]> * add swagger api path to readme Signed-off-by: Mathew Wicks <[email protected]> * regen swagger for camelCase change Signed-off-by: Mathew Wicks <[email protected]> * fix docstrings Signed-off-by: Mathew Wicks <[email protected]> --------- Signed-off-by: mohamed-ben-khemis <[email protected]> Signed-off-by: Mathew Wicks <[email protected]> Co-authored-by: Mathew Wicks <[email protected]>
1 parent 365c44b commit a5bf4ee

File tree

11 files changed

+571
-45
lines changed

11 files changed

+571
-45
lines changed

‎workspaces/backend/Makefile

+21-4
Original file line numberDiff line numberDiff line change
@@ -66,14 +66,24 @@ lint: golangci-lint ## Run golangci-lint linter
6666
lint-fix: golangci-lint ## Run golangci-lint linter and perform fixes
6767
$(GOLANGCI_LINT) run --fix
6868

69+
##@ Swagger
70+
ALL_GO_DIRS := $(shell find . -type f -name '*.go' -exec dirname {} \; | sed 's|^\./||' | sort -u)
71+
ALL_GO_DIRS_NO_CMD := $(shell echo "$(ALL_GO_DIRS)" | tr ' ' '\n' | grep -v '^cmd$$' | paste -sd, -)
72+
SWAG_DIRS := cmd,$(ALL_GO_DIRS_NO_CMD)
73+
74+
.PHONY: swag
75+
swag: SWAGGER
76+
$(SWAGGER) fmt -g main.go -d $(SWAG_DIRS)
77+
$(SWAGGER) init --parseDependency -q -g main.go -d $(SWAG_DIRS) --output openapi
78+
6979
##@ Build
7080

7181
.PHONY: build
72-
build: fmt vet ## Build backend binary.
82+
build: fmt vet swag ## Build backend binary.
7383
go build -o bin/backend cmd/main.go
7484

75-
.PHONY: run
76-
run: fmt vet ## Run a backend from your host.
85+
.PHONY: run
86+
run: fmt vet swag ## Run a backend from your host.
7787
go run ./cmd/main.go --port=$(PORT)
7888

7989
# If you wish to build the manager image targeting other platforms you can use the --platform flag.
@@ -115,10 +125,17 @@ $(LOCALBIN):
115125
KUBECTL ?= kubectl
116126
ENVTEST ?= $(LOCALBIN)/setup-envtest
117127
GOLANGCI_LINT = $(LOCALBIN)/golangci-lint
128+
SWAGGER = $(LOCALBIN)/swag
118129

119130
## Tool Versions
120131
ENVTEST_VERSION ?= release-0.19
121132
GOLANGCI_LINT_VERSION ?= v1.61.0
133+
SWAGGER_VERSION ?= v1.16.4
134+
135+
.PHONY: SWAGGER
136+
SWAGGER: $(SWAGGER)
137+
$(SWAGGER): $(LOCALBIN)
138+
$(call go-install-tool,$(SWAGGER),github.com/swaggo/swag/cmd/swag,$(SWAGGER_VERSION))
122139

123140
.PHONY: envtest
124141
envtest: $(ENVTEST) ## Download setup-envtest locally if necessary.
@@ -144,4 +161,4 @@ GOBIN=$(LOCALBIN) go install $${package} ;\
144161
mv $(1) $(1)-$(3) ;\
145162
} ;\
146163
ln -sf $(1)-$(3) $(1)
147-
endef
164+
endef

‎workspaces/backend/README.md

+1
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ make run PORT=8000
3636
|----------------------------------------------|------------------------|-----------------------------------------|
3737
| GET /api/v1/healthcheck | healthcheck_handler | Show application information |
3838
| GET /api/v1/namespaces | namespaces_handler | Get all Namespaces |
39+
| GET /api/v1/swagger/ | swagger_handler | Swagger API documentation |
3940
| GET /api/v1/workspaces | workspaces_handler | Get all Workspaces |
4041
| GET /api/v1/workspaces/{namespace} | workspaces_handler | Get all Workspaces from a namespace |
4142
| POST /api/v1/workspaces/{namespace} | workspaces_handler | Create a Workspace in a given namespace |

‎workspaces/backend/api/app.go

+8
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ import (
2828

2929
"github.com/kubeflow/notebooks/workspaces/backend/internal/config"
3030
"github.com/kubeflow/notebooks/workspaces/backend/internal/repositories"
31+
_ "github.com/kubeflow/notebooks/workspaces/backend/openapi"
3132
)
3233

3334
const (
@@ -51,6 +52,10 @@ const (
5152

5253
// namespaces
5354
AllNamespacesPath = PathPrefix + "/namespaces"
55+
56+
// swagger
57+
SwaggerPath = PathPrefix + "/swagger/*any"
58+
SwaggerDocPath = PathPrefix + "/swagger/doc.json"
5459
)
5560

5661
type App struct {
@@ -102,5 +107,8 @@ func (a *App) Routes() http.Handler {
102107
router.GET(AllWorkspaceKindsPath, a.GetWorkspaceKindsHandler)
103108
router.GET(WorkspaceKindsByNamePath, a.GetWorkspaceKindHandler)
104109

110+
// swagger
111+
router.GET(SwaggerPath, a.GetSwaggerHandler)
112+
105113
return a.recoverPanic(a.enableCORS(router))
106114
}

‎workspaces/backend/api/healthcheck_handler.go

+11
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,19 @@ import (
2020
"net/http"
2121

2222
"github.com/julienschmidt/httprouter"
23+
24+
_ "github.com/kubeflow/notebooks/workspaces/backend/internal/models/health_check"
2325
)
2426

27+
// GetHealthcheckHandler returns the health status of the application.
28+
//
29+
// @Summary Returns the health status of the application
30+
// @Description Provides a healthcheck response indicating the status of key services.
31+
// @Tags healthcheck
32+
// @Produce application/json
33+
// @Success 200 {object} health_check.HealthCheck "Successful healthcheck response"
34+
// @Failure 500 {object} ErrorEnvelope "Internal server error"
35+
// @Router /healthcheck [get]
2536
func (a *App) GetHealthcheckHandler(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
2637

2738
healthCheck, err := a.repositories.HealthCheck.HealthCheck(Version)

‎workspaces/backend/api/swagger_handler.go

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
/*
2+
Copyright 2024.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package api
18+
19+
import (
20+
"net/http"
21+
22+
"github.com/julienschmidt/httprouter"
23+
httpSwagger "github.com/swaggo/http-swagger/v2"
24+
)
25+
26+
func (a *App) GetSwaggerHandler(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
27+
httpSwagger.Handler(
28+
httpSwagger.URL(SwaggerDocPath),
29+
httpSwagger.DeepLinking(true),
30+
httpSwagger.DocExpansion("list"),
31+
httpSwagger.DomID("swagger-ui"),
32+
).ServeHTTP(w, r)
33+
}

‎workspaces/backend/cmd/main.go

+15
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,21 @@ import (
3232
"github.com/kubeflow/notebooks/workspaces/backend/internal/server"
3333
)
3434

35+
// @title Kubeflow Notebooks API
36+
// @version 1.0.0
37+
// @description This API provides endpoints to manage notebooks in a Kubernetes cluster.
38+
// @description For more information, visit https://www.kubeflow.org/docs/components/notebooks/
39+
40+
// @license.name Apache 2.0
41+
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
42+
43+
// @host localhost:4000
44+
// @BasePath /api/v1
45+
46+
// @schemes http https
47+
// @consumes application/json
48+
// @produces application/json
49+
3550
func main() {
3651
// Define command line flags
3752
cfg := &config.EnvConfig{}

‎workspaces/backend/go.mod

+15-10
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ require (
99
github.com/kubeflow/notebooks/workspaces/controller v0.0.0
1010
github.com/onsi/ginkgo/v2 v2.19.0
1111
github.com/onsi/gomega v1.33.1
12+
github.com/swaggo/http-swagger/v2 v2.0.2
13+
github.com/swaggo/swag v1.16.4
1214
k8s.io/api v0.31.0
1315
k8s.io/apimachinery v0.31.0
1416
k8s.io/apiserver v0.31.0
@@ -18,6 +20,7 @@ require (
1820
)
1921

2022
require (
23+
github.com/KyleBanks/depth v1.2.1 // indirect
2124
github.com/antlr4-go/antlr/v4 v4.13.0 // indirect
2225
github.com/asaskevich/govalidator v0.0.0-20190424111038-f61b66f89f4a // indirect
2326
github.com/beorn7/perks v1.0.1 // indirect
@@ -33,9 +36,10 @@ require (
3336
github.com/go-logr/logr v1.4.2 // indirect
3437
github.com/go-logr/stdr v1.2.2 // indirect
3538
github.com/go-logr/zapr v1.3.0 // indirect
36-
github.com/go-openapi/jsonpointer v0.19.6 // indirect
37-
github.com/go-openapi/jsonreference v0.20.2 // indirect
38-
github.com/go-openapi/swag v0.22.4 // indirect
39+
github.com/go-openapi/jsonpointer v0.21.0 // indirect
40+
github.com/go-openapi/jsonreference v0.21.0 // indirect
41+
github.com/go-openapi/spec v0.21.0 // indirect
42+
github.com/go-openapi/swag v0.23.0 // indirect
3943
github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
4044
github.com/gogo/protobuf v1.3.2 // indirect
4145
github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
@@ -51,7 +55,7 @@ require (
5155
github.com/inconshreveable/mousetrap v1.1.0 // indirect
5256
github.com/josharian/intern v1.0.0 // indirect
5357
github.com/json-iterator/go v1.1.12 // indirect
54-
github.com/mailru/easyjson v0.7.7 // indirect
58+
github.com/mailru/easyjson v0.9.0 // indirect
5559
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
5660
github.com/modern-go/reflect2 v1.0.2 // indirect
5761
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
@@ -63,6 +67,7 @@ require (
6367
github.com/spf13/cobra v1.8.1 // indirect
6468
github.com/spf13/pflag v1.0.5 // indirect
6569
github.com/stoewer/go-strcase v1.2.0 // indirect
70+
github.com/swaggo/files/v2 v2.0.2 // indirect
6671
github.com/x448/float16 v0.8.4 // indirect
6772
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.53.0 // indirect
6873
go.opentelemetry.io/otel v1.28.0 // indirect
@@ -75,14 +80,14 @@ require (
7580
go.uber.org/multierr v1.11.0 // indirect
7681
go.uber.org/zap v1.26.0 // indirect
7782
golang.org/x/exp v0.0.0-20230515195305-f3d0a9c9a5cc // indirect
78-
golang.org/x/net v0.26.0 // indirect
83+
golang.org/x/net v0.35.0 // indirect
7984
golang.org/x/oauth2 v0.21.0 // indirect
80-
golang.org/x/sync v0.7.0 // indirect
81-
golang.org/x/sys v0.21.0 // indirect
82-
golang.org/x/term v0.21.0 // indirect
83-
golang.org/x/text v0.16.0 // indirect
85+
golang.org/x/sync v0.11.0 // indirect
86+
golang.org/x/sys v0.30.0 // indirect
87+
golang.org/x/term v0.29.0 // indirect
88+
golang.org/x/text v0.22.0 // indirect
8489
golang.org/x/time v0.3.0 // indirect
85-
golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d // indirect
90+
golang.org/x/tools v0.30.0 // indirect
8691
gomodules.xyz/jsonpatch/v2 v2.4.0 // indirect
8792
google.golang.org/genproto/googleapis/api v0.0.0-20240528184218-531527333157 // indirect
8893
google.golang.org/genproto/googleapis/rpc v0.0.0-20240701130421-f6361c86f094 // indirect

0 commit comments

Comments
 (0)