OpenAPI: adds OpenAPI3.1 "examples" field to Schema and a Handler fie…

…ld to Operation

mux.go

@@ -90,6 +90,8 @@ func register[T any, B any](s *Server, method string, path string, controller ht
 		slog.Warn("error documenting openapi operation", "error", err)
 	}
 
+	operation.Handler = controller
+
 	return Route[T, B]{
 		operation: operation,
 	}

openapi3/openapi3.go

@@ -101,7 +101,7 @@ type Schema struct {
 	Format     string            `json:"format,omitempty" yaml:"format,omitempty"`
 	Required   []string          `json:"required,omitempty" yaml:"required,omitempty"`
 	Nullable   bool              `json:"nullable,omitempty" yaml:"nullable,omitempty"`
-	Example    string            `json:"example,omitempty" yaml:"example,omitempty"`
+	Examples   []string          `json:"examples,omitempty" yaml:"example,omitempty"`
 	Properties map[string]Schema `json:"properties,omitempty" yaml:"properties,omitempty"`
 	Items      *Schema           `json:"items,omitempty" yaml:"items,omitempty"`
 	MinLength  int               `json:"minLength,omitempty" yaml:"minLength,omitempty"`
@@ -140,6 +140,7 @@ type Operation struct {
 	Parameters  []*Parameter         `json:"parameters,omitempty" yaml:"parameters"`
 	Tags        []string             `json:"tags,omitempty" yaml:"tags"`
 	Responses   map[string]*Response `json:"responses,omitempty" yaml:"responses"`
+	Handler     interface{}          `json:"-" yaml:"-"`
 }
 
 type RequestBody struct {

openapi3/to_schema.go

@@ -24,13 +24,10 @@ func ToSchema(v any) *Schema {
 	}
 
 	if _, isTime := v.(time.Time); isTime {
-		s.Type = "string"
-		s.Format = "date-time"
-		s.Example = time.RFC3339
 		return &Schema{
-			Type:    "string",
-			Format:  "date-time",
-			Example: time.RFC3339,
+			Type:     "string",
+			Format:   "date-time",
+			Examples: []string{time.RFC3339},
 		}
 	}
 
@@ -43,7 +40,7 @@ func ToSchema(v any) *Schema {
 		}
 		one := reflect.New(itemType)
 		s.Items = ToSchema(one.Interface())
-		s.Example = "[]"
+		s.Examples = []string{"[]"}
 	case reflect.Struct:
 		for i := range value.NumField() {
 			structField := value.Type().Field(i)
@@ -59,7 +56,7 @@ func ToSchema(v any) *Schema {
 				s.Required = append(s.Required, fieldName)
 			}
 			parseValidate(&fieldSchema, structField.Tag.Get("validate"))
-			fieldSchema.Example = structField.Tag.Get("example")
+			fieldSchema.Examples = parseExampleList(structField.Tag.Get("example"))
 			fieldSchema.Format = structField.Tag.Get("format")
 			s.Properties[fieldName] = fieldSchema
 		}
@@ -78,6 +75,13 @@ func fieldName(s reflect.StructField) string {
 	return s.Name
 }
 
+func parseExampleList(examples string) []string {
+	if examples == "" {
+		return nil
+	}
+	return strings.Split(examples, ",")
+}
+
 type OpenAPIType string
 
 const (

openapi3/to_schema_test.go

@@ -72,7 +72,7 @@ func TestToSchema(t *testing.T) {
 			"type":"object",
 			"required":["a"],
 			"properties": {
-				"a":{"type":"string","example":"hello"},
+				"a":{"type":"string","examples":["hello"]},
 				"B":{"type":"integer"},
 				"C":{"type":"boolean"},
 				"Nested":{