Skip to content

Commit

Permalink
Add Swagger Config
Browse files Browse the repository at this point in the history
Signed-off-by: mohamed-ben-khemis <[email protected]>
  • Loading branch information
Mohamed-ben-khemis committed Feb 12, 2025
1 parent f22890d commit 5f04a46
Show file tree
Hide file tree
Showing 9 changed files with 321 additions and 0 deletions.
4 changes: 4 additions & 0 deletions workspaces/backend/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -145,3 +145,7 @@ mv $(1) $(1)-$(3) ;\
} ;\
ln -sf $(1)-$(3) $(1)
endef

watch:
$(call check_cluster_context)
@nodemon --exec go run cmd/main.go --signal SIGTERM
9 changes: 9 additions & 0 deletions workspaces/backend/api/app.go
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ import (
"net/http"

"github.com/julienschmidt/httprouter"
_ "github.com/kubeflow/notebooks/workspaces/backend/docs"
httpSwagger "github.com/swaggo/http-swagger"
"k8s.io/apimachinery/pkg/runtime"
"k8s.io/apiserver/pkg/authentication/authenticator"
"k8s.io/apiserver/pkg/authorization/authorizer"
Expand Down Expand Up @@ -51,6 +53,9 @@ const (

// namespaces
AllNamespacesPath = PathPrefix + "/namespaces"

// swagger
SwaggerPath = PathPrefix + "/swagger/*any"
)

type App struct {
Expand Down Expand Up @@ -102,5 +107,9 @@ func (a *App) Routes() http.Handler {
router.GET(AllWorkspaceKindsPath, a.GetWorkspaceKindsHandler)
router.GET(WorkspaceKindsByNamePath, a.GetWorkspaceKindHandler)

// swagger
router.GET(SwaggerPath, func(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
httpSwagger.Handler(httpSwagger.URL(PathPrefix + "/swagger/doc.json")).ServeHTTP(w, r)
})
return a.recoverPanic(a.enableCORS(router))
}
9 changes: 9 additions & 0 deletions workspaces/backend/api/healthcheck_handler.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,17 @@ import (
"net/http"

"github.com/julienschmidt/httprouter"
_ "github.com/kubeflow/notebooks/workspaces/backend/internal/models/health_check"
)

// GetHealthcheckHandler godoc
// @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} ErrorResponse "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)
Expand Down
8 changes: 8 additions & 0 deletions workspaces/backend/cmd/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,14 @@ 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/
// @host localhost:4000
// @BasePath /api/v1
// @license.name License: Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
func main() {
// Define command line flags
cfg := &config.EnvConfig{}
Expand Down
110 changes: 110 additions & 0 deletions workspaces/backend/docs/docs.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
// Package docs Code generated by swaggo/swag. DO NOT EDIT
package docs

import "github.com/swaggo/swag"

const docTemplate = `{
"schemes": {{ marshal .Schemes }},
"swagger": "2.0",
"info": {
"description": "{{escape .Description}}",
"title": "{{.Title}}",
"contact": {},
"license": {
"name": "License: 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.ErrorResponse"
}
}
}
}
}
},
"definitions": {
"api.ErrorResponse": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
},
"health_check.HealthCheck": {
"type": "object",
"properties": {
"status": {
"$ref": "#/definitions/health_check.ServiceStatus"
},
"system_info": {
"$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{},
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)
}
86 changes: 86 additions & 0 deletions workspaces/backend/docs/swagger.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
{
"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": "License: 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.ErrorResponse"
}
}
}
}
}
},
"definitions": {
"api.ErrorResponse": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
},
"health_check.HealthCheck": {
"type": "object",
"properties": {
"status": {
"$ref": "#/definitions/health_check.ServiceStatus"
},
"system_info": {
"$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"
}
}
}
}
}
59 changes: 59 additions & 0 deletions workspaces/backend/docs/swagger.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
basePath: /api/v1
definitions:
api.ErrorResponse:
properties:
code:
type: string
message:
type: string
type: object
health_check.HealthCheck:
properties:
status:
$ref: '#/definitions/health_check.ServiceStatus'
system_info:
$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: 'License: 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.ErrorResponse'
summary: Returns the health status of the application
tags:
- healthcheck
swagger: "2.0"
5 changes: 5 additions & 0 deletions workspaces/backend/go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -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 v1.3.4
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
Expand All @@ -20,6 +22,7 @@ require (
require (
github.com/antlr4-go/antlr/v4 v4.13.0 // indirect
github.com/asaskevich/govalidator v0.0.0-20190424111038-f61b66f89f4a // indirect
github.com/KyleBanks/depth v1.2.1 // indirect
github.com/beorn7/perks v1.0.1 // indirect
github.com/blang/semver/v4 v4.0.0 // indirect
github.com/cenkalti/backoff/v4 v4.3.0 // indirect
Expand All @@ -35,6 +38,7 @@ require (
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/spec v0.20.6 // indirect
github.com/go-openapi/swag v0.22.4 // indirect
github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
github.com/gogo/protobuf v1.3.2 // indirect
Expand Down Expand Up @@ -62,6 +66,7 @@ require (
github.com/prometheus/procfs v0.15.1 // indirect
github.com/spf13/cobra v1.8.1 // indirect
github.com/spf13/pflag v1.0.5 // indirect
github.com/swaggo/files v0.0.0-20220610200504-28940afbdbfe // indirect
github.com/stoewer/go-strcase v1.2.0 // indirect
github.com/x448/float16 v0.8.4 // indirect
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.53.0 // indirect
Expand Down
Loading

0 comments on commit 5f04a46

Please sign in to comment.