feat(parser): add ParseObject to generate OpenAPI schemas (#87)

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

bool_or_schema.go

@@ -78,7 +78,7 @@ func NewBoolOrSchema(v any) *BoolOrSchema {
 		return &BoolOrSchema{Allowed: v}
 	case *RefOrSpec[Schema]:
 		return &BoolOrSchema{Schema: v}
-	case *SchemaBulder:
+	case *SchemaBuilder:
 		return &BoolOrSchema{Schema: v.Build()}
 	default:
 		return nil

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,319 @@
+package openapi
+
+import (
+	"encoding/json"
+	"fmt"
+	"reflect"
+	"strings"
+)
+
+type parseOptions struct {
+	DefaultEncoding string // default encoding for the schema, used for []byte
+}
+
+type ParseOption func(*parseOptions)
+
+// WithDefaultEncoding sets the default encoding for the schema for []byte fields.
+// The default encoding is Base64Encoding.
+func WithDefaultEncoding(v string) ParseOption {
+	return func(opts *parseOptions) {
+		opts.DefaultEncoding = v
+	}
+}
+
+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], opts ...ParseOption) (*SchemaBuilder, error) {
+	opt := &parseOptions{
+		DefaultEncoding: Base64Encoding, // default encoding for []byte
+	}
+	for _, o := range opts {
+		o(opt)
+	}
+	t := reflect.TypeOf(obj)
+	if t == nil {
+		return NewSchemaBuilder().Type(NullType).GoType("nil"), nil
+	}
+	return parseObject(joinLoc("", t.String()), t, components, opt)
+}
+
+// MapKeyMustBeStringError is an error that is returned when the map key is not a string.
+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
+}
+
+// NewMapKeyMustBeStringError creates a new MapKeyMustBeStringError with the given location and key type.
+func NewMapKeyMustBeStringError(location string, keyType reflect.Kind) *MapKeyMustBeStringError {
+	return &MapKeyMustBeStringError{
+		Location: location,
+		KeyType:  keyType,
+	}
+}
+
+func parseObject(location string, t reflect.Type, components *Extendable[Components], opt *parseOptions) (*SchemaBuilder, 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, opt)
+		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(opt.DefaultEncoding).GoType("[]byte")
+	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, opt)
+				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, opt)
+				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
+			const toBeDeleted = "to be deleted"
+			components.Spec.Schemas[objName] = NewSchemaBuilder().Ref(toBeDeleted).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, opt)
+				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)
+		default:
+			// ignore unsupported types gracefully
+		}
+	}
+
+	return builder, nil
+}
+
+func applyTag(field *reflect.StructField, schema, parent *SchemaBuilder) (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 isTypeOverridden 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)
+			default:
+				// ignore unknown or unsupported tag prefixes gracefully
+			}
+			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 !isTypeOverridden {
+				schema.Type(part)
+				isTypeOverridden = true
+			} else {
+				schema.AddType(part)
+			}
+		case "addtype":
+			schema.AddType(part)
+		case "format":
+			schema.Format(part)
+		default:
+			// handle unknown or unsupported tag prefixes gracefully
+		}
+	}
+
+	return
+}