feat(parser): add ParseObject to generate OpenAPI schemas

Introduce ParseObject function to parse Go types into OpenAPI schema
representations, supporting structs, pointers, maps, slices, and primitives.
Handle tags for customizing schema fields, references, and metadata. This
enables automatic schema generation from Go types, improving integration
with OpenAPI components and reducing manual schema definitions.

Author: SVilgelm

README.md

@@ -28,6 +28,8 @@ go get github.com/sv-tools/openapi
     * `Validator.ValidateData()` method validates the data.
     * `Validator.ValidateDataAsJSON()` method validates the data by converting it into `map[string]any` type first using `json.Marshal` and `json.Unmarshal`. 
       **WARNING**: the function is slow due to double conversion.
+  * Added `ParseObject` function to create `SchemaBuilder` by parsing an object.
+    The function supports `json`, `yaml` and `openapi` field tags for the structs.
   * Use OpenAPI `v3.1.1` by default.
 
 ## Features

components.go

@@ -181,6 +181,7 @@ func (o *Components) validateSpec(location string, validator *Validator) []*vali
 		}
 		errs = append(errs, v.validateSpec(joinLoc(location, "responses", k), validator)...)
 	}
+
 	for k, v := range o.Parameters {
 		if !namePattern.MatchString(k) {
 			errs = append(errs, newValidationError(joinLoc(location, "parameters", k), "invalid name %q, must match %q", k, namePattern.String()))

parser.go

@@ -0,0 +1,290 @@
+package openapi
+
+import (
+	"encoding/json"
+	"fmt"
+	"reflect"
+	"strings"
+)
+
+const is64Bit = uint64(^uintptr(0)) == ^uint64(0)
+
+// ParseObject parses the object and returns the schema or the reference to the schema.
+//
+// The object can be a struct, pointer to struct, map, slice, pointer to map or slice, or any other type.
+// The object can contain fields with `json`, `yaml` or `openapi` tags.
+//
+//	`openapi:"<name>[,ref:<ref> || any other tags]"` tag:
+//	  - <name> is the name of the field in the schema, can be "-" to skip the field or empty to use the name from json, yaml tags or original field name.
+//	json schema fields:
+//	  - ref:<ref> is a reference to the schema, can not be used with jsonschema fields.
+//	  - required, marks the field as required by adding it to the required list of the parent schema.
+//	  - deprecated, marks the field as deprecated.
+//	  - title:<title>, sets the title of the field or summary for the fereference.
+//	  - summary:<summary>, sets the summary of the reference.
+//	  - description:<description>, sets the description of the field.
+//	  - type:<type> (boolean, integer, number, string, array, object), may be used multiple times.
+//	    The first usage overrides the default type, all other types are added.
+//	  - addtype:<type>, adds additional type, may be used multiple times.
+//	  - format:<format>, sets the format of the type.
+//
+// The `components` parameter is needed to store the schemas of the structs, and to avoid the circular references.
+// In case of the given object is struct, the function will return a reference to the schema stored in the components
+// Otherwise, the function will return the schema itself.
+func ParseObject(obj any, components *Extendable[Components]) (*SchemaBulder, error) {
+	t := reflect.TypeOf(obj)
+	if t == nil {
+		return NewSchemaBuilder().Type(NullType).GoType("nil"), nil
+	}
+	return parseObject(joinLoc("", t.String()), t, components)
+}
+
+type MapKeyMustBeStringError struct {
+	Location string
+	KeyType  reflect.Kind
+}
+
+func (e *MapKeyMustBeStringError) Error() string {
+	return fmt.Sprintf("%s: unsupported map key type %s, expected string", e.Location, e.KeyType)
+}
+
+func (e *MapKeyMustBeStringError) Is(target error) bool {
+	if target == nil {
+		return false
+	}
+	_, ok := target.(*MapKeyMustBeStringError)
+	return ok
+}
+
+func NewMapKeyMustBeStringError(location string, keyType reflect.Kind) *MapKeyMustBeStringError {
+	return &MapKeyMustBeStringError{
+		Location: location,
+		KeyType:  keyType,
+	}
+}
+
+func parseObject(location string, t reflect.Type, components *Extendable[Components]) (*SchemaBulder, error) {
+	if t == nil {
+		return NewSchemaBuilder().Type(NullType).GoType("nil"), nil
+	}
+	kind := t.Kind()
+	if kind == reflect.Ptr {
+		builder, err := parseObject(location, t.Elem(), components)
+		if err != nil {
+			return nil, err
+		}
+		if builder.IsRef() {
+			builder = NewSchemaBuilder().OneOf(
+				builder.Build(),
+				NewSchemaBuilder().Type(NullType).Build(),
+			)
+		} else {
+			builder.AddType(NullType)
+		}
+		return builder, nil
+	}
+	if kind == reflect.Interface {
+		return NewSchemaBuilder().GoType("any"), nil
+	}
+	obj := reflect.New(t).Elem()
+	builder := NewSchemaBuilder().GoType(fmt.Sprintf("%T", obj.Interface()))
+	switch obj.Interface().(type) {
+	case bool:
+		builder.Type(BooleanType)
+	case int, uint:
+		if is64Bit {
+			builder.Type(IntegerType).Format(Int64Format)
+		} else {
+			builder.Type(IntegerType).Format(Int32Format)
+		}
+	case int8, int16, int32, uint8, uint16, uint32:
+		builder.Type(IntegerType).Format(Int32Format)
+	case int64, uint64:
+		builder.Type(IntegerType).Format(Int64Format)
+	case float32:
+		builder.Type(NumberType).Format(FloatFormat)
+	case float64:
+		builder.Type(NumberType).Format(DoubleFormat)
+	case string:
+		builder.Type(StringType)
+	case []byte:
+		builder.Type(StringType).ContentEncoding(Base64Encoding).GoType("[]byte") // TODO: create an option for default ContentEncoding
+	case json.Number:
+		builder.Type(NumberType).GoPackage(t.PkgPath())
+	case json.RawMessage:
+		builder.Type(StringType).ContentMediaType("application/json").GoPackage(t.PkgPath())
+	default:
+		switch kind {
+		case reflect.Array, reflect.Slice:
+			var elemSchema any
+			elem := t.Elem()
+			if elem.Kind() == reflect.Interface {
+				elemSchema = true
+			} else {
+				var err error
+				elemSchema, err = parseObject(location, elem, components)
+				if err != nil {
+					return nil, err
+				}
+			}
+			builder.Type(ArrayType).Items(NewBoolOrSchema(elemSchema)).GoType("")
+		case reflect.Map:
+			if k := t.Key().Kind(); k != reflect.String {
+				return nil, NewMapKeyMustBeStringError(location, k)
+			}
+			var elemSchema any
+			elem := t.Elem()
+			if elem.Kind() == reflect.Interface {
+				elemSchema = true
+			} else {
+				var err error
+				elemSchema, err = parseObject(location, elem, components)
+				if err != nil {
+					return nil, err
+				}
+			}
+			builder.Type(ObjectType).AdditionalProperties(NewBoolOrSchema(elemSchema)).GoType("")
+		case reflect.Struct:
+			objName := strings.ReplaceAll(t.PkgPath()+"."+t.Name(), "/", ".")
+			if components.Spec.Schemas[objName] != nil {
+				return NewSchemaBuilder().Ref("#/components/schemas/" + objName), nil
+			}
+			// add a temporary schema to avoid circular references
+			if components.Spec.Schemas == nil {
+				components.Spec.Schemas = make(map[string]*RefOrSpec[Schema], 1)
+			}
+			// reserve the name of the schema
+			components.Spec.Schemas[objName] = NewSchemaBuilder().Ref("to be deleted").Build()
+			var allOf []*RefOrSpec[Schema]
+			for i := range t.NumField() {
+				field := t.Field(i)
+				// skip unexported fields
+				if !field.IsExported() {
+					continue
+				}
+				fieldSchema, err := parseObject(joinLoc(location, field.Name), obj.Field(i).Type(), components)
+				if err != nil {
+					// remove the temporary schema
+					delete(components.Spec.Schemas, objName)
+					return nil, err
+				}
+				if field.Anonymous {
+					allOf = append(allOf, fieldSchema.Build())
+					continue
+				}
+				name := applyTag(&field, fieldSchema, builder)
+				// skip the field if it's marked as "-"
+				if name == "-" {
+					continue
+				}
+				builder.AddProperty(name, fieldSchema.Build())
+			}
+			if len(allOf) > 0 {
+				allOf = append(allOf, builder.Type(ObjectType).GoType("").Build())
+				builder = NewSchemaBuilder().AllOf(allOf...).GoType(t.String())
+			} else {
+				builder.Type(ObjectType)
+			}
+			builder.GoPackage(t.PkgPath())
+			components.Spec.Schemas[objName] = builder.Build()
+			builder = NewSchemaBuilder().Ref("#/components/schemas/" + objName)
+		}
+	}
+
+	return builder, nil
+}
+
+func applyTag(field *reflect.StructField, schema, parent *SchemaBulder) (name string) {
+	name = field.Name
+
+	for _, tagName := range []string{"json", "yaml"} {
+		if tag, ok := field.Tag.Lookup(tagName); ok {
+			parts := strings.SplitN(tag, ",", 2)
+			if len(parts) > 0 {
+				part := strings.TrimSpace(parts[0])
+				if part != "" {
+					name = part
+					break
+				}
+			}
+		}
+	}
+
+	tag, ok := field.Tag.Lookup("openapi")
+	if !ok {
+		return
+	}
+	parts := strings.Split(tag, ",")
+	if len(parts) == 0 {
+		return
+	}
+
+	if parts[0] != "" {
+		name = parts[0]
+	}
+	if name == "-" {
+		return parts[0]
+	}
+	parts = parts[1:]
+	if len(parts) == 0 {
+		return
+	}
+
+	if strings.HasPrefix(parts[0], "ref:") {
+		schema.Ref(parts[0][4:])
+	}
+
+	var isTypeOverriden bool
+
+	for _, part := range parts {
+		prefixIndex := strings.Index(part, ":")
+		var prefix string
+		if prefixIndex == -1 {
+			prefix = part
+		} else {
+			prefix = part[:prefixIndex]
+			if prefixIndex == len(part)-1 {
+				part = ""
+			}
+			part = part[prefixIndex+1:]
+		}
+
+		// the tags for the references only
+		if schema.IsRef() {
+			switch prefix {
+			case "required":
+				parent.AddRequired(name)
+			case "description":
+				schema.Description(part)
+			case "title", "summary":
+				schema.Title(part)
+			}
+			continue
+		}
+
+		switch prefix {
+		case "required":
+			parent.AddRequired(name)
+		case "deprecated":
+			schema.Deprecated(true)
+		case "title":
+			schema.Title(part)
+		case "description":
+			schema.Description(part)
+		case "type":
+			// first type overrides the default type, all other types are added
+			if !isTypeOverriden {
+				schema.Type(part)
+				isTypeOverriden = true
+			} else {
+				schema.AddType(part)
+			}
+		case "addtype":
+			schema.AddType(part)
+		case "format":
+			schema.Format(part)
+		}
+	}
+
+	return
+}