openapi3gen: add CreateComponentSchemas option to export object schemas to components (#935)

Co-authored-by: Omer E <33223663+tcdsv@users.noreply.github.com>

Author: fenollp

.github/docs/openapi3filter_fixtures.txt

@@ -27,6 +27,12 @@ type ExcludeSchemaSentinel struct{}
 
 func (err *ExcludeSchemaSentinel) Error() string
 
+type ExportComponentSchemasOptions struct {
+ExportComponentSchemas bool
+ExportTopLevelSchema bool
+ExportGenerics bool
+}
+
 type Generator struct {
 Types map[reflect.Type]*openapi3.SchemaRef
 
@@ -50,6 +56,12 @@ func (g *Generator) NewSchemaRefForValue(value interface{}, schemas openapi3.Sch
 type Option func(*generatorOpt)
  Option allows tweaking SchemaRef generation
 
+func CreateComponentSchemas(exso ExportComponentSchemasOptions) Option
+ CreateComponents changes the default behavior to add all schemas as
+ components Reduces duplicate schemas in routes
+
+func CreateTypeNameGenerator(tngnrt TypeNameGenerator) Option
+
 func SchemaCustomizer(sc SchemaCustomizerFn) Option
  SchemaCustomizer allows customization of the schema that is generated for a
  field, for example to support an additional tagging scheme
@@ -77,3 +89,5 @@ type SetSchemar interface {
  their specification. Useful when some custom datatype is needed and/or some
  custom logic is needed on how the schema values would be generated
 
+type TypeNameGenerator func(t reflect.Type) string
+

.github/docs/openapi3gen.txt

@@ -3,7 +3,8 @@ set -o pipefail
 
 outdir=.github/docs
 mkdir -p "$outdir"
-for pkgpath in $(git ls-files | grep / | while read -r path; do dirname "$path"; done | sort -u | grep -vE '[.]git|testdata|cmd/'); do
+for pkgpath in $(git ls-files | grep / | while read -r path; do dirname "$path"; done | sort -u | grep -vE '[.]git|testdata|internal|cmd/'); do
+echo $pkgpath
 go doc -all ./"$pkgpath" | tee "$outdir/${pkgpath////_}.txt"
 done
 

docs.sh

@@ -0,0 +1,5 @@
+package subpkg
+
+type Child struct {
+Name string `yaml:"name"`
+}

openapi3gen/internal/subpkg/sub_type.go

@@ -6,6 +6,7 @@ import (
 "fmt"
 "math"
 "reflect"
+"regexp"
 "strings"
 "time"
 
@@ -42,10 +43,20 @@ type SetSchemar interface {
 SetSchema(*openapi3.Schema)
 }
 
+type ExportComponentSchemasOptions struct {
+ExportComponentSchemas bool
+ExportTopLevelSchema bool
+ExportGenerics bool
+}
+
+type TypeNameGenerator func(t reflect.Type) string
+
 type generatorOpt struct {
-useAllExportedFields bool
-throwErrorOnCycle bool
-schemaCustomizer SchemaCustomizerFn
+useAllExportedFields bool
+throwErrorOnCycle bool
+schemaCustomizer SchemaCustomizerFn
+exportComponentSchemas ExportComponentSchemasOptions
+typeNameGenerator TypeNameGenerator
 }
 
 // UseAllExportedFields changes the default behavior of only
@@ -54,6 +65,10 @@ func UseAllExportedFields() Option {
 return func(x *generatorOpt) { x.useAllExportedFields = true }
 }
 
+func CreateTypeNameGenerator(tngnrt TypeNameGenerator) Option {
+return func(x *generatorOpt) { x.typeNameGenerator = tngnrt }
+}
+
 // ThrowErrorOnCycle changes the default behavior of creating cycle
 // refs to instead error if a cycle is detected.
 func ThrowErrorOnCycle() Option {
@@ -66,6 +81,13 @@ func SchemaCustomizer(sc SchemaCustomizerFn) Option {
 return func(x *generatorOpt) { x.schemaCustomizer = sc }
 }
 
+// CreateComponents changes the default behavior
+// to add all schemas as components
+// Reduces duplicate schemas in routes
+func CreateComponentSchemas(exso ExportComponentSchemasOptions) Option {
+return func(x *generatorOpt) { x.exportComponentSchemas = exso }
+}
+
 // NewSchemaRefForValue is a shortcut for NewGenerator(...).NewSchemaRefForValue(...)
 func NewSchemaRefForValue(value interface{}, schemas openapi3.Schemas, opts ...Option) (*openapi3.SchemaRef, error) {
 g := NewGenerator(opts...)
@@ -83,6 +105,7 @@ type Generator struct {
 SchemaRefs map[*openapi3.SchemaRef]int
 
 // componentSchemaRefs is a set of schemas that must be defined in the components to avoid cycles
+// or if we have specified create components schemas
 componentSchemaRefs map[string]struct{}
 }
 
@@ -111,9 +134,16 @@ func (g *Generator) NewSchemaRefForValue(value interface{}, schemas openapi3.Sch
 return nil, err
 }
 for ref := range g.SchemaRefs {
-if _, ok := g.componentSchemaRefs[ref.Ref]; ok && schemas != nil {
-schemas[ref.Ref] = &openapi3.SchemaRef{
-Value: ref.Value,
+refName := ref.Ref
+if g.opts.exportComponentSchemas.ExportComponentSchemas && strings.HasPrefix(refName, "#/components/schemas/") {
+refName = strings.TrimPrefix(refName, "#/components/schemas/")
+}
+
+if _, ok := g.componentSchemaRefs[refName]; ok && schemas != nil {
+if ref.Value != nil && ref.Value.Properties != nil {
+schemas[refName] = &openapi3.SchemaRef{
+Value: ref.Value,
+}
 }
 }
 if strings.HasPrefix(ref.Ref, "#/components/schemas/") {
@@ -298,6 +328,14 @@ func (g *Generator) generateWithoutSaving(parents []*theTypeInfo, t reflect.Type
 schema.Type = &openapi3.Types{"string"}
 schema.Format = "date-time"
 } else {
+typeName := g.generateTypeName(t)
+
+if _, ok := g.componentSchemaRefs[typeName]; ok && g.opts.exportComponentSchemas.ExportComponentSchemas {
+// Check if we have already parsed this component schema ref based on the name of the struct
+// and use that if so
+return openapi3.NewSchemaRef(fmt.Sprintf("#/components/schemas/%s", typeName), schema), nil
+}
+
 for _, fieldInfo := range typeInfo.Fields {
 // Only fields with JSON tag are considered (by default)
 if !fieldInfo.HasJSONTag && !g.opts.useAllExportedFields {
@@ -347,6 +385,7 @@ func (g *Generator) generateWithoutSaving(parents []*theTypeInfo, t reflect.Type
 g.SchemaRefs[ref]++
 schema.WithPropertyRef(fieldName, ref)
 }
+
 }
 
 // Object only if it has properties
@@ -362,6 +401,7 @@ func (g *Generator) generateWithoutSaving(parents []*theTypeInfo, t reflect.Type
 v.SetSchema(schema)
 }
 }
+
 }
 
 if g.opts.schemaCustomizer != nil {
@@ -370,9 +410,40 @@ func (g *Generator) generateWithoutSaving(parents []*theTypeInfo, t reflect.Type
 }
 }
 
+if !g.opts.exportComponentSchemas.ExportComponentSchemas || t.Kind() != reflect.Struct {
+return openapi3.NewSchemaRef(t.Name(), schema), nil
+}
+
+// Best way I could find to check that
+// this current type is a generic
+isGeneric, err := regexp.Match(`^.*\[.*\]$`, []byte(t.Name()))
+if err != nil {
+return nil, err
+}
+
+if isGeneric && !g.opts.exportComponentSchemas.ExportGenerics {
+return openapi3.NewSchemaRef(t.Name(), schema), nil
+}
+
+// For structs we add the schemas to the component schemas
+if len(parents) > 1 || g.opts.exportComponentSchemas.ExportTopLevelSchema {
+typeName := g.generateTypeName(t)
+
+g.componentSchemaRefs[typeName] = struct{}{}
+return openapi3.NewSchemaRef(fmt.Sprintf("#/components/schemas/%s", typeName), schema), nil
+}
+
 return openapi3.NewSchemaRef(t.Name(), schema), nil
 }
 
+func (g *Generator) generateTypeName(t reflect.Type) string {
+if g.opts.typeNameGenerator != nil {
+return g.opts.typeNameGenerator(t)
+}
+
+return t.Name()
+}
+
 func (g *Generator) generateCycleSchemaRef(t reflect.Type, schema *openapi3.Schema) *openapi3.SchemaRef {
 var typeName string
 switch t.Kind() {
@@ -391,7 +462,7 @@ func (g *Generator) generateCycleSchemaRef(t reflect.Type, schema *openapi3.Sche
 mapSchema.AdditionalProperties = openapi3.AdditionalProperties{Schema: ref}
 return openapi3.NewSchemaRef("", mapSchema)
 default:
-typeName = t.Name()
+typeName = g.generateTypeName(t)
 }
 
 g.componentSchemaRefs[typeName] = struct{}{}