Add support for ffschemaext

pkg/ffapi/openapi3.go

@@ -21,6 +21,7 @@ import (
 	"fmt"
 	"log"
 	"net/http"
+	"net/url"
 	"reflect"
 	"regexp"
 	"sort"
@@ -74,7 +75,11 @@ type BaseURLVariable struct {
 	Description string
 }
 
-var customRegexRemoval = regexp.MustCompile(`{(\w+)\:[^}]+}`)
+var (
+	customRegexRemoval = regexp.MustCompile(`{(\w+)\:[^}]+}`)
+	// Check ffExtension key starts with "x-"
+	ffExtensionKeyRegexp = regexp.MustCompile(`^x-.+$`)
+)
 
 type SwaggerGen struct {
 	options *SwaggerGenOptions
@@ -184,10 +189,45 @@ func (sg *SwaggerGen) ffOutputTagHandler(ctx context.Context, route *Route, name
 	return sg.ffTagHandler(ctx, route, name, tag, schema)
 }
 
+func (sg *SwaggerGen) applyFFExtensionsTag(ctx context.Context, schema *openapi3.Schema, tag string) error {
+	if tag == "" {
+		return nil
+	}
+	for _, extension := range strings.Split(tag, "&") {
+		kv := strings.SplitN(strings.TrimSpace(extension), "=", 2)
+		if len(kv) != 2 {
+			return i18n.NewError(ctx, i18n.MsgFFExtensionsInvalid, extension)
+		}
+		keyEnc := strings.TrimSpace(kv[0])
+		key, err := url.QueryUnescape(keyEnc)
+		if err != nil {
+			return i18n.NewError(ctx, i18n.MsgFFExtensionsInvalidKeyEncoding, keyEnc)
+		}
+		if !ffExtensionKeyRegexp.MatchString(key) {
+			return i18n.NewError(ctx, i18n.MsgFFExtensionsInvalidKey, key)
+		}
+		valEnc := strings.TrimSpace(kv[1])
+		val, err := url.QueryUnescape(valEnc)
+		if err != nil {
+			return i18n.NewError(ctx, i18n.MsgFFExtensionsInvalidValueEncoding, valEnc, key)
+		}
+		if schema.Extensions == nil {
+			schema.Extensions = make(map[string]interface{})
+		}
+		schema.Extensions[key] = val
+	}
+	return nil
+}
+
 func (sg *SwaggerGen) ffTagHandler(ctx context.Context, route *Route, name string, tag reflect.StructTag, schema *openapi3.Schema) error {
 	if ffEnum := tag.Get("ffenum"); ffEnum != "" {
 		schema.Enum = fftypes.FFEnumValues(ffEnum)
 	}
+	if ffExtensions := tag.Get("ffschemaext"); ffExtensions != "" {
+		if err := sg.applyFFExtensionsTag(ctx, schema, ffExtensions); err != nil {
+			return err
+		}
+	}
 	if sg.isTrue(tag.Get("ffexclude")) {
 		return &openapi3gen.ExcludeSchemaSentinel{}
 	}

pkg/ffapi/openapi3_test.go

@@ -64,6 +64,32 @@ type TestStruct2 struct {
 	JSONAny1 *fftypes.JSONAny `ffstruct:"ut1" json:"jsonAny1,omitempty"`
 }
 
+type TestExtensions struct {
+	String1 string `ffstruct:"ut1" json:"string1" ffschemaext:"x-key1=value1"`
+	String2 string `ffstruct:"ut1" json:"string2" ffschemaext:"x-key1=value1,x-key2=value2"`
+	String3 string `ffstruct:"ut1" json:"string3" ffschemaext:""`
+}
+
+type TestExtensionsBad1 struct {
+	String1 string `ffstruct:"ut1" json:"string1" ffschemaext:"x-key1"`
+}
+
+type TestExtensionsBad2 struct {
+	String1 string `ffstruct:"ut1" json:"string1" ffschemaext:"key1=value1,key2=value2"`
+}
+
+type TestExtensionsBad3 struct {
+	String1 string `ffstruct:"ut1" json:"string1" ffschemaext:"x-=value1"`
+}
+
+type TestExtensionsBadKeyEncoding struct {
+	String1 string `ffstruct:"ut1" json:"string1" ffschemaext:"x-key%=value1"`
+}
+
+type TestExtensionsBadValueEncoding struct {
+	String1 string `ffstruct:"ut1" json:"string1" ffschemaext:"x-key1=value1%"`
+}
+
 var ExampleDesc = i18n.FFM(language.AmericanEnglish, "TestKey", "Test Description")
 
 var example2TagName = "Example 2"
@@ -193,6 +219,18 @@ var testRoutes = []*Route{
 		},
 		Tag: example2TagName,
 	},
+	{
+		Name:       "op8",
+		Path:       "example8",
+		Method:     http.MethodGet,
+		PathParams: nil,
+		QueryParams: nil,
+		Description: ExampleDesc,
+		JSONInputValue: func() interface{} { return nil},
+		JSONOutputValue: func() interface{} { return &TestExtensions{} },
+		JSONOutputCodes: []int{http.StatusOK},
+	},
+
 }
 
 type TestInOutType struct {
@@ -578,3 +616,108 @@ func TestExcludeFromOpenAPI(t *testing.T) {
 	err := doc.Validate(context.Background())
 	assert.NoError(t, err)
 }
+
+func TestExtensionsBad1Fail(t *testing.T) {
+	routes := []*Route{
+		{
+			Name:           "bad1",
+			Path:           "extensions",
+			Method:         http.MethodGet,
+			JSONInputValue: func() interface{} { return nil },
+			JSONOutputValue: func() interface{} { return &TestExtensionsBad1{} },
+			JSONOutputCodes: []int{http.StatusOK},
+		},
+	}
+
+	assert.PanicsWithValue(t, "invalid schema: FF00258: Invalid extension 'x-key1' - extensions must follow the format 'x-<name>=<value>'", func() {
+		_ = NewSwaggerGen(&SwaggerGenOptions{
+			Title:   "UnitTest",
+			Version: "1.0",
+			BaseURL: "http://localhost:12345/api/v1",
+		}).Generate(context.Background(), routes)
+	})
+}
+
+func TestExtensionsBad2Fail(t *testing.T) {
+	routes := []*Route{
+		{
+			Name:           "bad2",
+			Path:           "extensions",
+			Method:         http.MethodGet,
+			JSONInputValue: func() interface{} { return nil },
+			JSONOutputValue: func() interface{} { return &TestExtensionsBad2{} },
+			JSONOutputCodes: []int{http.StatusOK},
+		},
+	}
+
+	assert.PanicsWithValue(t, "invalid schema: FF00259: Invalid extension key 'key1' - extension keys must follow the format 'x-<name>'", func() {
+		_ = NewSwaggerGen(&SwaggerGenOptions{
+			Title:   "UnitTest",
+			Version: "1.0",
+			BaseURL: "http://localhost:12345/api/v1",
+		}).Generate(context.Background(), routes)
+	})
+}
+
+func TestExtensionsBad3Fail(t *testing.T) {
+	routes := []*Route{
+		{
+			Name:           "bad3",
+			Path:           "extensions",
+			Method:         http.MethodGet,
+			JSONInputValue: func() interface{} { return nil },
+			JSONOutputValue: func() interface{} { return &TestExtensionsBad3{} },
+			JSONOutputCodes: []int{http.StatusOK},
+		},
+	}
+
+	assert.PanicsWithValue(t, "invalid schema: FF00259: Invalid extension key 'x-' - extension keys must follow the format 'x-<name>'", func() {
+		_ = NewSwaggerGen(&SwaggerGenOptions{
+			Title:   "UnitTest",
+			Version: "1.0",
+			BaseURL: "http://localhost:12345/api/v1",
+		}).Generate(context.Background(), routes)
+	})
+}
+
+func TestExtensionsBadKeyEncodingFail(t *testing.T) {
+	routes := []*Route{
+		{
+			Name:           "badKeyEncoding",
+			Path:           "extensions",
+			Method:         http.MethodGet,
+			JSONInputValue: func() interface{} { return nil },
+			JSONOutputValue: func() interface{} { return &TestExtensionsBadKeyEncoding{} },
+			JSONOutputCodes: []int{http.StatusOK},
+		},
+	}
+
+	assert.PanicsWithValue(t, "invalid schema: FF00260: Invalid extension key encoding 'x-key%'", func() {
+		_ = NewSwaggerGen(&SwaggerGenOptions{
+			Title:   "UnitTest",
+			Version: "1.0",
+			BaseURL: "http://localhost:12345/api/v1",
+		}).Generate(context.Background(), routes)
+	})
+}
+
+func TestExtensionsBadValueEncodingFail(t *testing.T) {
+	routes := []*Route{
+		{
+			Name:           "badValueEncoding",
+			Path:           "extensions",
+			Method:         http.MethodGet,
+			JSONInputValue: func() interface{} { return nil },
+			JSONOutputValue: func() interface{} { return &TestExtensionsBadValueEncoding{} },
+			JSONOutputCodes: []int{http.StatusOK},
+		},
+	}
+
+	assert.PanicsWithValue(t, "invalid schema: FF00261: Invalid extension value encoding 'value1%' for key 'x-key1'", func() {
+		_ = NewSwaggerGen(&SwaggerGenOptions{
+			Title:   "UnitTest",
+			Version: "1.0",
+			BaseURL: "http://localhost:12345/api/v1",
+		}).Generate(context.Background(), routes)
+	})
+}

pkg/i18n/en_base_error_messages.go

@@ -192,4 +192,8 @@ var (
 	MsgRoutePathNotStartWithSlash                  = ffe("FF00255", "Route path '%s' must not start with '/'")
 	MsgMethodNotAllowed                            = ffe("FF00256", "Method not allowed", http.StatusMethodNotAllowed)
 	MsgInvalidLogLevel                             = ffe("FF00257", "Invalid log level: '%s'", http.StatusBadRequest)
+	MsgFFExtensionsInvalid                         = ffe("FF00258", "Invalid extension '%s' - extensions must follow the format 'x-<name>=<value>'", http.StatusBadRequest)
+	MsgFFExtensionsInvalidKey                      = ffe("FF00259", "Invalid extension key '%s' - extension keys must follow the format 'x-<name>'", http.StatusBadRequest)
+	MsgFFExtensionsInvalidKeyEncoding              = ffe("FF00260", "Invalid extension key encoding '%s'", http.StatusBadRequest)
+	MsgFFExtensionsInvalidValueEncoding            = ffe("FF00261", "Invalid extension value encoding '%s' for key '%s'", http.StatusBadRequest)
 )