updating documentation and tests for registering versions

Signed-off-by: Alex Lovell-Troy <alex@lovelltroy.org>

Author: alexlovelltroy

cmd/fabrica/generate.go

@@ -64,6 +64,10 @@ func newGenerateCommand() *cobra.Command {
 		Long: `Generate server handlers, storage adapters, client code, and OpenAPI specs
 from your resource definitions.
 
+For versioned APIs (apis.yaml), this also generates
+pkg/apiversion/registry_generated.go, which is required for apiVersion
+validation in the server middleware.
+
 Examples:
   fabrica generate                    # Generate all
   fabrica generate --handlers         # Just handlers

docs/guides/versioning.md

@@ -641,9 +641,12 @@ See [Migration Guide](https://docs.example.io/migration) for step-by-step instru
 
 ### Error: "apiVersion not supported"
 
-**Cause**: Client requested a version not in the `apis.yaml` versions list.
+**Cause**: Client requested a version not in the `apis.yaml` versions list, or
+the version registry was not generated/imported in the server.
 
 **Solution**: Add the version to `apis.yaml` or update the client to use a supported version.
+If the registry is missing, run `fabrica generate` and ensure
+`_ "<module>/pkg/apiversion"` is imported in `cmd/server/main.go`.
 
 ```yaml
 # apis.yaml

docs/reference/cli.md

@@ -360,6 +360,7 @@ Generated Files:
 - Files ending in `_generated.go` are completely overwritten
 - Your resource definitions (`*_types.go`) are never modified
 - Run from project root directory
+- Versioned APIs require `pkg/apiversion/registry_generated.go` for apiVersion validation
 
 ---
 

test/integration/versioning_test.go

@@ -5,6 +5,7 @@
 package integration
 
 import (
+	"net/http"
 	"os"
 	"path/filepath"
 	"testing"
@@ -189,6 +190,31 @@ func (s *VersioningSuite) TestJSONCompatibility() {
 	s.Require().NoError(err, "generated models should contain JSON marshaling tags")
 }
 
+// TestUnsupportedAPIVersionRejected verifies invalid apiVersion returns 406 when registry is present
+func (s *VersioningSuite) TestUnsupportedAPIVersionRejected() {
+	project := s.createProject("apiversion-unsupported", "github.com/test/unsupported", "file")
+
+	err := project.Initialize(s.fabricaBinary)
+	s.Require().NoError(err, "project initialization should succeed")
+
+	err = project.AddResource(s.fabricaBinary, "Device")
+	s.Require().NoError(err, "adding resource should succeed")
+
+	err = project.Generate(s.fabricaBinary)
+	s.Require().NoError(err, "code generation should succeed")
+
+	project.AssertFileExists("pkg/apiversion/registry_generated.go")
+
+	err = project.StartServerRuntime()
+	s.Require().NoError(err, "server should start")
+
+	body := `{"apiVersion":"example.com/v2asdasda","kind":"Device","metadata":{"name":"device-100"},"spec":{}}`
+	resp, respBody, err := project.HTTPCall(http.MethodPost, "/devices", body, nil)
+	s.Require().NoError(err, "request should succeed")
+	s.Require().Equal(http.StatusNotAcceptable, resp.StatusCode)
+	s.Require().Contains(string(respBody), "Unsupported version")
+}
+
 // TestRun is the entry point for the versioning test suite
 func TestVersioningSuite(t *testing.T) {
 	suite.Run(t, new(VersioningSuite))