Merge pull request #208 from chrisbygrave/ff-openapi-extensions

Add support for ffextensions

Author: peterbroadhurst

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,37 @@ 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
+	}
+	q, err := url.ParseQuery(tag)
+	if err != nil {
+		return i18n.WrapError(ctx, err, i18n.MsgFFExtensionsInvalid, tag)
+	}
+	for extension, values := range q {
+		for _, value := range values {
+			if !ffExtensionKeyRegexp.MatchString(extension) {
+				return i18n.NewError(ctx, i18n.MsgFFExtensionsInvalidEncoding, extension)
+			}
+			if schema.Extensions == nil {
+				schema.Extensions = make(map[string]interface{})
+			}
+			schema.Extensions[extension] = value
+		}
+	}
+	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,20 @@ 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-key1=value2&x-key2=value2%26value3"`
+	String3 string `ffstruct:"ut1" json:"string3" ffschemaext:""`
+}
+
+type TestExtensionsBadKey struct {
+	String1 string `ffstruct:"ut1" json:"string1" ffschemaext:"x-=value1"`
+}
+
+type TestExtensionsBadEncoding 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 +207,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 +604,45 @@ func TestExcludeFromOpenAPI(t *testing.T) {
 	err := doc.Validate(context.Background())
 	assert.NoError(t, err)
 }
+
+func TestExtensionsBadEncodingFail(t *testing.T) {
+	routes := []*Route{
+		{
+			Name:           "badEncoding",
+			Path:           "extensions",
+			Method:         http.MethodGet,
+			JSONInputValue: func() interface{} { return nil },
+			JSONOutputValue: func() interface{} { return &TestExtensionsBadEncoding{} },
+			JSONOutputCodes: []int{http.StatusOK},
+		},
+	}
+
+	assert.PanicsWithValue(t, "invalid schema: FF00258: Invalid extension 'x-key1=value1%' - extensions should be RFC 3986 compliant query parameter format (e.g. x-name=value with percent-encoding for special characters): invalid URL escape \"%\"", func() {
+		_ = NewSwaggerGen(&SwaggerGenOptions{
+			Title:   "UnitTest",
+			Version: "1.0",
+			BaseURL: "http://localhost:12345/api/v1",
+		}).Generate(context.Background(), routes)
+	})
+}
+
+func TestExtensionsBadKeyFail(t *testing.T) {
+	routes := []*Route{
+		{
+			Name:           "bad3",
+			Path:           "extensions",
+			Method:         http.MethodGet,
+			JSONInputValue: func() interface{} { return nil },
+			JSONOutputValue: func() interface{} { return &TestExtensionsBadKey{} },
+			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)
+	})
+}

pkg/i18n/en_base_error_messages.go

@@ -192,4 +192,6 @@ 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 should be RFC 3986 compliant query parameter format (e.g. x-name=value with percent-encoding for special characters)", http.StatusBadRequest)
+	MsgFFExtensionsInvalidEncoding                 = ffe("FF00259", "Invalid extension key '%s' - extension keys must follow the format 'x-<name>'", http.StatusBadRequest)
 )