feat: Add simple versioning support (#22)

Makefile

@@ -46,9 +46,9 @@ lint: ## Run all available linters
 lint-fix: ## Run all available linters and fix the issues
 	golangci-lint run --timeout=5m --fix
 
-.PHONY: spec
+.PHONY: typespec
 ## Type spec:
-spec: ### Run compilation of OpenAPI specification
+typespec: ### Run compilation of OpenAPI specification
 	@echo "Compiling OpenAPI spec"
 	sh ./scripts/compile-spec.sh	
 

api/item.go → api/v1/item.go

@@ -1,4 +1,4 @@
-package api
+package v1
 
 import (
 	"github.com/glass-cms/glasscms/item"

api/item_test.go → api/v1/item_test.go

@@ -1,10 +1,10 @@
-package api_test
+package v1_test
 
 import (
 	"testing"
 	"time"
 
-	"github.com/glass-cms/glasscms/api"
+	v1 "github.com/glass-cms/glasscms/api/v1"
 	"github.com/glass-cms/glasscms/item"
 	"github.com/glass-cms/glasscms/parser"
 	"github.com/stretchr/testify/assert"
@@ -104,7 +104,7 @@ func TestItem_MapToDomain(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 
-			apiItem := &api.Item{
+			apiItem := &v1.Item{
 				Content:     tt.fields.Content,
 				CreateTime:  tt.fields.CreateTime,
 				DisplayName: tt.fields.DisplayName,

cmd/server/start.go

@@ -10,6 +10,8 @@ import (
 	"github.com/glass-cms/glasscms/item"
 	ctx "github.com/glass-cms/glasscms/lib/context"
 	"github.com/glass-cms/glasscms/server"
+	"github.com/glass-cms/glasscms/server/handler"
+	v1 "github.com/glass-cms/glasscms/server/handler/v1"
 	"github.com/lmittmann/tint"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
@@ -91,7 +93,9 @@ func (c *StartCommand) Execute(cmd *cobra.Command, _ []string) error {
 		return err
 	}
 
-	server, err := server.New(c.logger, item.NewRepository(db))
+	v1Handler := v1.NewAPIHandler(c.logger, item.NewRepository(db))
+
+	server, err := server.New(c.logger, []handler.VersionedHandler{v1Handler})
 	if err != nil {
 		return err
 	}

docs/development/code-gen.md

@@ -0,0 +1,21 @@
+# Code Generation
+
+This project uses [TypeSpec](https://typespec.io/) for describing the API of the application. The TypeSpec is compiled in an OpenAPI 3.0 specification file, which is then used to generate the client and server code.
+
+## Generating the OpenAPI specification
+
+The TypeSpec files are located in the `typespec` directory. To compile the OpenAPI specification, run the following command:
+
+```bash
+make typespec
+```
+
+The OpenAPI specification will be generated in the `openapi` directory.
+
+## Generating the client and server code
+
+The client and server code is generated using the [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen) module. To generate the code, run the following command:
+
+```bash
+go generate ./...
+```

generate.go

@@ -1,3 +1,3 @@
 package main
 
-//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=codegen-server.yaml openapi.yaml
+//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=openapi/codegen.cfg.v1.yaml openapi/openapi.v1.yaml

codegen-server.yaml → openapi/codegen.cfg.v1.yaml

@@ -1,5 +1,5 @@
-package: api
+package: v1
 generate:
   std-http-server: true
   models: true
-output: api/api.gen.go
+output: api/v1/api.gen.go

openapi.yaml → openapi/openapi.v1.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.0
 info:
   title: GlassCMS API
-  version: 0.0.0
+  version: v1
 tags: []
 paths:
   /items:
@@ -81,3 +81,7 @@ components:
           type: object
           additionalProperties: {}
       description: Item represents an individual content item.
+    Versions:
+      type: string
+      enum:
+        - v1

scripts/compile-spec.sh

@@ -6,5 +6,5 @@
 
 current_dir=$(pwd)
 cd typespec || exit
-tsp compile . --emit @typespec/openapi3 --option "@typespec/openapi3.emitter-output-dir=${current_dir}"
+tsp compile . --emit @typespec/openapi3 --option "@typespec/openapi3.emitter-output-dir=${current_dir}/openapi"
 cd "$current_dir" || exit

server/handler/handler.go

@@ -0,0 +1,9 @@
+package handler
+
+import "net/http"
+
+// VersionedHandler is an interface that defines an HTTP handler.
+type VersionedHandler interface {
+	// HttpHandler returns an http.Handler that implements the API for a specific version.
+	Handler(baseRouter *http.ServeMux, middlewares []func(http.Handler) http.Handler) http.Handler
+}

server/handler/v1/item.go

@@ -0,0 +1,17 @@
+package v1
+
+import "net/http"
+
+func (s *APIHandler) ItemsDelete(w http.ResponseWriter, _ *http.Request) {
+	// TODO.
+	w.WriteHeader(http.StatusNotImplemented)
+}
+
+func (s *APIHandler) ItemsList(w http.ResponseWriter, _ *http.Request) {
+	// TODO.
+	w.WriteHeader(http.StatusNotImplemented)
+}
+
+func (s *APIHandler) ItemsCreate(w http.ResponseWriter, _ *http.Request) {
+	w.WriteHeader(http.StatusNotImplemented)
+}

server/handler/v1/v1.go

@@ -0,0 +1,47 @@
+// Package v1 implements the API handlers for the v1 version of the Glass CMS API.
+package v1
+
+import (
+	"log/slog"
+	"net/http"
+
+	v1 "github.com/glass-cms/glasscms/api/v1"
+	"github.com/glass-cms/glasscms/item"
+	"github.com/glass-cms/glasscms/server/handler"
+)
+
+type APIHandler struct {
+	logger     *slog.Logger
+	repository *item.Repository
+}
+
+// NewAPIHandler returns a new instance of ApiHandler.
+func NewAPIHandler(
+	logger *slog.Logger,
+	repo *item.Repository,
+) *APIHandler {
+	return &APIHandler{
+		logger:     logger,
+		repository: repo,
+	}
+}
+
+// Handler returns an http.Handler that implements the API.
+func (s *APIHandler) Handler(
+	baseRouter *http.ServeMux,
+	middlewares []func(http.Handler) http.Handler,
+) http.Handler {
+	convertedMiddlewares := make([]v1.MiddlewareFunc, len(middlewares))
+	for i, mw := range middlewares {
+		convertedMiddlewares[i] = v1.MiddlewareFunc(mw)
+	}
+
+	return v1.HandlerWithOptions(s, v1.StdHTTPServerOptions{
+		BaseURL:     "/v1",
+		BaseRouter:  baseRouter,
+		Middlewares: convertedMiddlewares,
+	})
+}
+
+var _ v1.ServerInterface = (*APIHandler)(nil)
+var _ handler.VersionedHandler = (*APIHandler)(nil)

server/server.go

@@ -7,9 +7,8 @@ import (
 	"net/http"
 	"time"
 
-	"github.com/glass-cms/glasscms/api"
-	"github.com/glass-cms/glasscms/item"
 	"github.com/glass-cms/glasscms/lib/middleware"
+	"github.com/glass-cms/glasscms/server/handler"
 )
 
 const (
@@ -22,32 +21,27 @@ const (
 type Server struct {
 	logger *slog.Logger
 	server *http.Server
-
-	repository *item.Repository
 }
 
-var _ api.ServerInterface = (*Server)(nil)
-
 func New(
 	logger *slog.Logger,
-	repo *item.Repository,
+	handlers []handler.VersionedHandler,
 	opts ...Option,
 ) (*Server, error) {
 	server := &Server{
-		logger:     logger,
-		repository: repo,
+		logger: logger,
 	}
 
-	serverOpts := api.StdHTTPServerOptions{
-		Middlewares: []api.MiddlewareFunc{
+	serveMux := http.NewServeMux()
+
+	for _, h := range handlers {
+		_ = h.Handler(serveMux, []func(http.Handler) http.Handler{
 			middleware.MediaType("application/json"),
-		},
+		})
 	}
 
-	handler := api.HandlerWithOptions(server, serverOpts)
-
 	server.server = &http.Server{
-		Handler:      handler,
+		Handler:      serveMux,
 		Addr:         fmt.Sprintf(":%v", DefaultPort),
 		ReadTimeout:  DefaultReadTimeout,
 		WriteTimeout: DefaultWriteTimeout,

typespec/main.tsp

@@ -1,14 +1,20 @@
 import "@typespec/http";
 import "@typespec/rest";
 import "@typespec/openapi3";
+import "@typespec/versioning";
 
 using TypeSpec.Http;
 using TypeSpec.Rest;
 
 @service({
     title: "GlassCMS API",
 })
-namespace GlassCMS;
+@TypeSpec.Versioning.versioned(Versions)
+namespace GlassCMSCore;
+
+enum Versions {
+    v1,
+}
 
 @route("/items")
 namespace Items {

typespec/package.json

@@ -6,7 +6,8 @@
     "@typespec/compiler": "latest",
     "@typespec/http": "latest",
     "@typespec/rest": "latest",
-    "@typespec/openapi3": "latest"
+    "@typespec/openapi3": "latest",
+    "@typespec/versioning": "latest"
   },
   "private": true
 }