[openapi] configurable openapi docs

Author: capcom6

internal/config/config.go

@@ -24,6 +24,14 @@ type Gateway struct {
 type HTTP struct {
 	Listen  string   `yaml:"listen" envconfig:"HTTP__LISTEN"`   // listen address
 	Proxies []string `yaml:"proxies" envconfig:"HTTP__PROXIES"` // proxies
+
+	OpenAPI OpenAPI `yaml:"openapi"`
+}
+
+type OpenAPI struct {
+	Enabled bool   `yaml:"enabled" envconfig:"HTTP__OPENAPI__ENABLED"`
+	Host    string `yaml:"host" envconfig:"HTTP__OPENAPI__HOST"`
+	Path    string `yaml:"path" envconfig:"HTTP__OPENAPI__PATH"`
 }
 
 type Database struct {

internal/config/module.go

@@ -9,6 +9,7 @@ import (
 	"github.com/android-sms-gateway/server/internal/sms-gateway/modules/messages"
 	"github.com/android-sms-gateway/server/internal/sms-gateway/modules/push"
 	"github.com/android-sms-gateway/server/internal/sms-gateway/modules/sse"
+	"github.com/android-sms-gateway/server/internal/sms-gateway/openapi"
 	"github.com/capcom6/go-infra-fx/config"
 	"github.com/capcom6/go-infra-fx/db"
 	"github.com/capcom6/go-infra-fx/http"
@@ -97,4 +98,11 @@ var Module = fx.Module(
 			sse.WithKeepAlivePeriod(time.Duration(cfg.SSE.KeepAlivePeriodSeconds) * time.Second),
 		)
 	}),
+	fx.Provide(func(cfg Config) openapi.Config {
+		return openapi.Config{
+			Enabled: cfg.HTTP.OpenAPI.Enabled,
+			Host:    cfg.HTTP.OpenAPI.Host,
+			Path:    cfg.HTTP.OpenAPI.Path,
+		}
+	}),
 )

internal/sms-gateway/app.go

@@ -18,6 +18,7 @@ import (
 	"github.com/android-sms-gateway/server/internal/sms-gateway/modules/settings"
 	"github.com/android-sms-gateway/server/internal/sms-gateway/modules/sse"
 	"github.com/android-sms-gateway/server/internal/sms-gateway/modules/webhooks"
+	"github.com/android-sms-gateway/server/internal/sms-gateway/openapi"
 	"github.com/capcom6/go-infra-fx/cli"
 	"github.com/capcom6/go-infra-fx/db"
 	"github.com/capcom6/go-infra-fx/http"
@@ -36,6 +37,7 @@ var Module = fx.Module(
 	appdb.Module,
 	http.Module,
 	validator.Module,
+	openapi.Module(),
 	handlers.Module,
 	auth.Module,
 	push.Module,

internal/sms-gateway/handlers/root.go

@@ -1,46 +1,31 @@
 package handlers
 
 import (
-	"github.com/android-sms-gateway/server/internal/version"
-	apidoc "github.com/android-sms-gateway/server/pkg/swagger"
+	"github.com/android-sms-gateway/server/internal/sms-gateway/openapi"
 	"github.com/gofiber/fiber/v2"
-	"github.com/gofiber/fiber/v2/middleware/etag"
-	"github.com/gofiber/swagger"
 )
 
 type rootHandler struct {
-	healthHandler *healthHandler
+	healthHandler  *healthHandler
+	openapiHandler *openapi.Handler
 }
 
 func (h *rootHandler) Register(app *fiber.App) {
 	app.Use(func(c *fiber.Ctx) error {
-		if c.Path() == "/api" {
-			return c.Redirect("/docs/", fiber.StatusMovedPermanently)
+		if c.Path() == "/api" || c.Path() == "/api/" {
+			return c.Redirect("/api/docs/", fiber.StatusMovedPermanently)
 		}
 
 		return c.Next()
 	})
 
 	h.healthHandler.Register(app)
-	h.registerDocs(app)
+	h.openapiHandler.Register(app.Group("/api/docs"))
 }
 
-func (h *rootHandler) registerDocs(router fiber.Router) error {
-	apidoc.SwaggerInfo.Version = version.AppVersion
-	router.Use("/docs/*",
-		etag.New(etag.Config{
-			Weak: true,
-		}),
-		swagger.New(swagger.Config{
-			Layout: "BaseLayout",
-		}),
-	)
-
-	return nil
-}
-
-func newRootHandler(healthHandler *healthHandler) *rootHandler {
+func newRootHandler(healthHandler *healthHandler, openapiHandler *openapi.Handler) *rootHandler {
 	return &rootHandler{
-		healthHandler: healthHandler,
+		healthHandler:  healthHandler,
+		openapiHandler: openapiHandler,
 	}
 }

internal/sms-gateway/openapi/config.go

@@ -0,0 +1,7 @@
+package openapi
+
+type Config struct {
+	Enabled bool
+	Host    string
+	Path    string
+}

pkg/swagger/docs.go renamed to internal/sms-gateway/openapi/docs.go

@@ -1,5 +1,5 @@
-// Package swagger Code generated by swaggo/swag. DO NOT EDIT
-package swagger
+// Package openapi Code generated by swaggo/swag. DO NOT EDIT
+package openapi
 
 import "github.com/swaggo/swag"
 

internal/sms-gateway/openapi/module.go

@@ -0,0 +1,16 @@
+package openapi
+
+import (
+	"go.uber.org/fx"
+	"go.uber.org/zap"
+)
+
+func Module() fx.Option {
+	return fx.Module(
+		"openapi",
+		fx.Decorate(func(log *zap.Logger) *zap.Logger {
+			return log.Named("openapi")
+		}),
+		fx.Provide(New),
+	)
+}

internal/sms-gateway/openapi/openapi.go

@@ -0,0 +1,49 @@
+package openapi
+
+import (
+	"github.com/android-sms-gateway/server/internal/version"
+	"github.com/gofiber/fiber/v2"
+	"github.com/gofiber/fiber/v2/middleware/etag"
+	"github.com/gofiber/swagger"
+)
+
+//go:generate swag init --parseDependency --tags=User,System --outputTypes go -d ../../../ -g ./cmd/sms-gateway/main.go -o ../../../internal/sms-gateway/openapi
+
+type Handler struct {
+	config Config
+}
+
+func New(config Config) *Handler {
+	return &Handler{
+		config: config,
+	}
+}
+
+func (s *Handler) Register(router fiber.Router) {
+	if !s.config.Enabled {
+		return
+	}
+
+	SwaggerInfo.Version = version.AppVersion
+	SwaggerInfo.Host = s.config.Host
+	SwaggerInfo.BasePath = s.config.Path
+
+	router.Use("*",
+		// Pre-middleware: set host/scheme dynamically
+		func(c *fiber.Ctx) error {
+			if SwaggerInfo.Host == "" {
+				SwaggerInfo.Host = c.Hostname()
+				SwaggerInfo.BasePath = "/api"
+			}
+
+			scheme := "http"
+			if c.Secure() {
+				scheme = "https"
+			}
+			SwaggerInfo.Schemes = []string{scheme}
+			return c.Next()
+		},
+		etag.New(etag.Config{Weak: true}),
+		swagger.New(swagger.Config{Layout: "BaseLayout"}),
+	)
+}