feat: openapi enhancements:

* Correct name for properties, now fields with tag "name,omitempty" are exported as "name" instead of "name,omitempty"
* Handle anonymous structs
* Paths with no methods are discarded
* Resources or Actions can be marked to not export

Author: fulldump

boxopenapi/openapi.go

@@ -11,6 +11,19 @@ import (
 
 type JSON = map[string]any
 
+func isFalse(a any) bool {
+
+	if v, ok := a.(string); ok && v == "false" {
+		return true
+	}
+
+	if v, ok := a.(bool); ok && v == false {
+		return true
+	}
+
+	return false
+}
+
 // Spec returns a valid OpenAPI spec from a box router ready to be used.
 func Spec(api *box.B) OpenAPI {
 
@@ -19,6 +32,10 @@ func Spec(api *box.B) OpenAPI {
 
 	walk(api.R, func(r *box.R) {
 
+		if isFalse(r.GetAttribute("openapi")) {
+			return
+		}
+
 		if len(r.GetActions()) == 0 {
 			return
 		}
@@ -30,6 +47,11 @@ func Spec(api *box.B) OpenAPI {
 		parameters := getParams(r)
 
 		for _, action := range r.GetActions() {
+
+			if isFalse(action.GetAttribute("openapi")) {
+				return
+			}
+
 			method := strings.ToLower(action.HttpMethod)
 
 			inputs, outputs, _ := describeHandler(action.GetHandler())
@@ -75,7 +97,9 @@ func Spec(api *box.B) OpenAPI {
 			}
 		}
 
-		paths[path] = methods
+		if len(methods) > 0 {
+			paths[path] = methods
+		}
 	})
 
 	return OpenAPI{
@@ -96,31 +120,9 @@ func Spec(api *box.B) OpenAPI {
 	}
 }
 
-func schemaStruct(schemas JSON, item reflect.Type) JSON {
-
-	name := item.Name()
-	{
-		// Normalize name:
-		name = strings.TrimRight(name, "]")
-		parts := strings.Split(name, ".")
-		name = parts[len(parts)-1]
-	}
-
-	result := JSON{
-		"$ref": "#/components/schemas/" + name,
-	}
-
-	if _, exists := schemas[name]; exists {
-		return result
-	}
+func schemaStructFields(schemas JSON, item reflect.Type) JSON {
 
 	properties := JSON{}
-	definition := JSON{
-		"type":       "object",
-		"required":   []string{},
-		"properties": properties,
-	}
-	schemas[name] = definition
 
 	// follow pointers
 	for item.Kind() == reflect.Ptr {
@@ -130,20 +132,61 @@ func schemaStruct(schemas JSON, item reflect.Type) JSON {
 	for i := 0; i < item.NumField(); i++ {
 		f := item.Field(i)
 
+		if f.Anonymous {
+			anonymousProperties := schemaStructFields(schemas, f.Type)
+			for k, v := range anonymousProperties {
+				properties[k] = v
+			}
+			continue
+		}
+
 		definition := schemaAny(schemas, f.Type)
 
 		if v, ok := f.Tag.Lookup("description"); ok {
 			definition["description"] = v
 		}
 
 		name := f.Tag.Get("json")
+		name = strings.Split(name, ",")[0]
 		if name == "" {
 			name = f.Name
 		}
 
 		properties[name] = definition
 	}
 
+	return properties
+}
+
+func schemaStruct(schemas JSON, item reflect.Type) JSON {
+
+	name := item.Name()
+	{
+		// Normalize name:
+		name = strings.TrimRight(name, "]")
+		parts := strings.Split(name, ".")
+		name = parts[len(parts)-1]
+	}
+
+	result := JSON{
+		"$ref": "#/components/schemas/" + name,
+	}
+
+	if _, exists := schemas[name]; exists {
+		return result
+	}
+
+	schemas[name] = JSON{} // Avoid infinite loop in recursive objects
+
+	properties := schemaStructFields(schemas, item)
+
+	definition := JSON{
+		"type":       "object",
+		"required":   []string{},
+		"properties": properties,
+	}
+	schemas[name] = definition
+
 	return result
 }
 

boxopenapi/openapi_test.go

@@ -22,15 +22,26 @@ func newApiExample() *box.B {
 	b.Handle("GET", "/scalarValues", GetScalarValues)
 	b.Handle("GET", "/time.Time", GetTypeTime)
 
+	b.Handle("GET", "/hidden-action", func() {}).SetAttribute("openapi", false)
+
+	b.Group("/hidden-resource").SetAttribute("openapi", false)
+	b.Handle("GET", "/hidden-resource", func() {})
+
 	return b
 }
 
 type User struct {
 	Id     string   `json:"id" description:"User identifier"`
 	Name   string   `json:"name" description:"User name"`
-	Tags   []string `json:"tags" description:"User tags"`
+	Tags   []string `json:"tags,omitempty" description:"User tags"`
 	Age    int      `json:"age" description:"User age"`
 	Active bool     `json:"active" description:"User active"`
+	AnonymousFields
+}
+
+type AnonymousFields struct {
+	CreationDate time.Time `json:"creation_date" description:"Creation date"`
+	ModifiedDate time.Time `json:"modifiedd_date" description:"Modification date"`
 }
 
 func ListUsers() []*User {
@@ -235,6 +246,22 @@ func TestOpenApi(t *testing.T) {
 							},
 							"type": "array",
 						},
+						"creation_date": JSON{
+							"description": "Creation date",
+							"examples": []string{
+								"2006-01-02T15:04:05Z07:00",
+							},
+							"format": "date-time",
+							"type":   "string",
+						},
+						"modifiedd_date": JSON{
+							"description": "Modification date",
+							"examples": []string{
+								"2006-01-02T15:04:05Z07:00",
+							},
+							"format": "date-time",
+							"type":   "string",
+						},
 					},
 					"required": []JSON{},
 					"type":     "object",