Add support for external references

Author: deepmap-marcinr

experimental/README.md

@@ -167,8 +167,51 @@ name-substitutions:
     foo: MyCustomFoo  # "foo" becomes "MyCustomFoo" instead of "Foo"
   property-names:
     bar: MyCustomBar  # "bar" field becomes "MyCustomBar"
+
+# Import mapping: resolve external $refs to Go packages
+import-mapping:
+  # Map external spec files to their Go package paths
+  ../common/api.yaml: github.com/org/project/common
+  https://example.com/specs/shared.yaml: github.com/org/shared
+  # Use "-" to indicate types should stay in the current package
+  ./local-types.yaml: "-"
+```
+
+### External References
+
+When your OpenAPI spec references schemas from other files:
+
+```yaml
+# In your spec
+components:
+  schemas:
+    Order:
+      properties:
+        customer:
+          $ref: '../common/api.yaml#/components/schemas/Customer'
+```
+
+Configure import-mapping to tell oapi-codegen where to find those types:
+
+```yaml
+import-mapping:
+  ../common/api.yaml: github.com/org/project/common
+```
+
+The generated code will import the external package and reference types with a hashed alias:
+
+```go
+import (
+    ext_a1b2c3d4 "github.com/org/project/common"
+)
+
+type Order struct {
+    Customer *ext_a1b2c3d4.Customer `json:"customer,omitempty"`
+}
 ```
 
+**Important:** You must generate types for the external spec separately. The import-mapping only tells oapi-codegen how to reference types that already exist in another package.
+
 Use with `-config`:
 ```bash
 go run ./cmd/oapi-codegen -config config.yaml openapi.yaml
@@ -191,15 +234,34 @@ go run ./cmd/oapi-codegen -config config.yaml openapi.yaml
 | `string` | `email` | `Email` (custom type) |
 | `string` | `binary` | `File` (custom type) |
 
-### Name Override Limitations
+### Preprocessing with OpenAPI Overlays
+
+For advanced customizations (renaming types, modifying schemas, adding extensions), preprocess your spec using the [OpenAPI Overlay Specification](https://learn.openapis.org/overlay/):
+
+```yaml
+# overlay.yaml
+overlay: 1.0.0
+info:
+  title: My customizations
+  version: 1.0.0
+actions:
+  - target: $.components.schemas.Cat
+    update:
+      x-go-name: Kitty
+  - target: $.components.schemas.Pet.properties.id
+    update:
+      type: string
+      format: uuid
+```
+
+Apply with [speakeasy-api/openapi-overlay](https://github.com/speakeasy-api/openapi-overlay):
+```bash
+go install github.com/speakeasy-api/openapi-overlay@latest
+openapi-overlay apply --overlay=overlay.yaml --spec=openapi.yaml > modified.yaml
+go run ./cmd/oapi-codegen -package myapi modified.yaml
+```
 
-> **Note:** The current `name-substitutions` system only overrides individual name *parts* during conversion, not full generated type names.
->
-> For example, if you have a schema at `#/components/schemas/Cat`:
-> - Setting `type-names: {Cat: Kitty}` will produce `KittySchemaComponent` (stable) and `Kitty` (short)
-> - You cannot currently override the full stable name `CatSchemaComponent` to something completely different
->
-> Full type name overrides (by schema path or generated name) are not yet implemented.
+Or use [libopenapi](https://pb33f.io/libopenapi/overlays/) programmatically if you need to integrate into a build pipeline.
 
 ## Development
 

experimental/cmd/oapi-codegen/main.go

@@ -8,6 +8,7 @@ import (
 	"strings"
 
 	"github.com/pb33f/libopenapi"
+	"github.com/pb33f/libopenapi/datamodel"
 	"gopkg.in/yaml.v3"
 
 	"github.com/oapi-codegen/oapi-codegen/experimental/internal/codegen"
@@ -40,7 +41,20 @@ func main() {
 		os.Exit(1)
 	}
 
-	doc, err := libopenapi.NewDocument(specData)
+	// Get the absolute path of the spec file's directory for resolving external refs
+	absSpecPath, err := filepath.Abs(specPath)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error getting absolute path: %v\n", err)
+		os.Exit(1)
+	}
+	specDir := filepath.Dir(absSpecPath)
+
+	// Configure libopenapi with BasePath to resolve external references
+	docConfig := datamodel.NewDocumentConfiguration()
+	docConfig.BasePath = specDir
+	docConfig.AllowFileReferences = true
+
+	doc, err := libopenapi.NewDocumentWithConfiguration(specData, docConfig)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "error parsing spec: %v\n", err)
 		os.Exit(1)

experimental/internal/codegen/codegen.go

@@ -26,12 +26,12 @@ func Generate(doc libopenapi.Document, cfg Configuration) (string, error) {
 	ComputeSchemaNames(schemas, converter)
 
 	// Pass 3: Generate Go code
-	gen := NewTypeGenerator(cfg.TypeMapping, converter)
+	importResolver := NewImportResolver(cfg.ImportMapping)
+	gen := NewTypeGenerator(cfg.TypeMapping, converter, importResolver)
 	gen.IndexSchemas(schemas)
 
 	output := NewOutput(cfg.PackageName)
-	output.AddImport("encoding/json", "")
-	output.AddImport("fmt", "")
+	// Note: encoding/json and fmt imports are added by generateType when needed
 
 	// Generate types for each schema
 	for _, desc := range schemas {
@@ -113,6 +113,9 @@ func generateStructType(gen *TypeGenerator, desc *SchemaDescriptor) string {
 
 	// Check if we need additionalProperties handling
 	if gen.HasAdditionalProperties(desc) {
+		// Mixed properties need encoding/json and fmt for marshal/unmarshal
+		gen.AddJSONImports()
+
 		addPropsType := gen.AdditionalPropertiesType(desc)
 		structCode := GenerateStructWithAdditionalProps(desc.StableName, fields, addPropsType, doc)
 
@@ -310,6 +313,7 @@ func generateAllOfType(gen *TypeGenerator, desc *SchemaDescriptor) string {
 	var code string
 	if len(unionFields) > 0 {
 		// Has union members - need custom marshal/unmarshal
+		gen.AddJSONImports()
 		code = generateAllOfStructWithUnions(desc.StableName, finalFields, unionFields, doc)
 	} else {
 		// Simple case - just flattened fields
@@ -479,6 +483,9 @@ func generateAnyOfType(gen *TypeGenerator, desc *SchemaDescriptor) string {
 		return ""
 	}
 
+	// Union types need encoding/json and fmt for marshal/unmarshal
+	gen.AddJSONImports()
+
 	doc := extractDescription(desc.Schema)
 	structCode := GenerateUnionType(desc.StableName, members, false, doc)
 	marshalCode := GenerateUnionMarshalAnyOf(desc.StableName, members)
@@ -501,6 +508,9 @@ func generateOneOfType(gen *TypeGenerator, desc *SchemaDescriptor) string {
 		return ""
 	}
 
+	// Union types need encoding/json and fmt for marshal/unmarshal
+	gen.AddJSONImports()
+
 	doc := extractDescription(desc.Schema)
 	structCode := GenerateUnionType(desc.StableName, members, true, doc)
 	marshalCode := GenerateUnionMarshalOneOf(desc.StableName, members)

experimental/internal/codegen/configuration.go

@@ -1,5 +1,11 @@
 package codegen
 
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"sort"
+)
+
 type Configuration struct {
 	// PackageName which will be used in all generated files
 	PackageName string `yaml:"package"`
@@ -11,10 +17,76 @@ type Configuration struct {
 	NameMangling NameMangling `yaml:"name-mangling,omitempty"`
 	// NameSubstitutions allows direct overrides of generated names
 	NameSubstitutions NameSubstitutions `yaml:"name-substitutions,omitempty"`
+	// ImportMapping maps external spec file paths to Go package import paths.
+	// Example: {"../common/api.yaml": "github.com/org/project/common"}
+	// Use "-" as the value to indicate types should be in the current package.
+	ImportMapping map[string]string `yaml:"import-mapping,omitempty"`
 }
 
 // ApplyDefaults merges user configuration on top of default values.
 func (c *Configuration) ApplyDefaults() {
 	c.TypeMapping = DefaultTypeMapping.Merge(c.TypeMapping)
 	c.NameMangling = DefaultNameMangling().Merge(c.NameMangling)
 }
+
+// ExternalImport represents an external package import with its alias.
+type ExternalImport struct {
+	Alias string // Short alias for use in generated code (e.g., "ext_a1b2c3")
+	Path  string // Full import path (e.g., "github.com/org/project/common")
+}
+
+// ImportResolver resolves external references to Go package imports.
+type ImportResolver struct {
+	mapping map[string]ExternalImport // spec file path -> import info
+}
+
+// NewImportResolver creates an ImportResolver from the configuration's import mapping.
+func NewImportResolver(importMapping map[string]string) *ImportResolver {
+	resolver := &ImportResolver{
+		mapping: make(map[string]ExternalImport),
+	}
+
+	for specPath, pkgPath := range importMapping {
+		if pkgPath == "-" {
+			// "-" means current package, no import needed
+			resolver.mapping[specPath] = ExternalImport{Alias: "", Path: ""}
+		} else {
+			resolver.mapping[specPath] = ExternalImport{
+				Alias: hashImportAlias(pkgPath),
+				Path:  pkgPath,
+			}
+		}
+	}
+
+	return resolver
+}
+
+// Resolve looks up an external spec file path and returns its import info.
+// Returns nil if the path is not in the mapping.
+func (r *ImportResolver) Resolve(specPath string) *ExternalImport {
+	if imp, ok := r.mapping[specPath]; ok {
+		return &imp
+	}
+	return nil
+}
+
+// AllImports returns all external imports sorted by alias.
+func (r *ImportResolver) AllImports() []ExternalImport {
+	var imports []ExternalImport
+	for _, imp := range r.mapping {
+		if imp.Path != "" { // Skip current package markers
+			imports = append(imports, imp)
+		}
+	}
+	sort.Slice(imports, func(i, j int) bool {
+		return imports[i].Alias < imports[j].Alias
+	})
+	return imports
+}
+
+// hashImportAlias generates a short, deterministic alias from an import path.
+// Uses first 8 characters of SHA256 hash prefixed with "ext_".
+func hashImportAlias(importPath string) string {
+	h := sha256.Sum256([]byte(importPath))
+	return "ext_" + hex.EncodeToString(h[:])[:8]
+}

experimental/internal/codegen/schema.go

@@ -64,6 +64,30 @@ func (d *SchemaDescriptor) IsReference() bool {
 	return d.Ref != ""
 }
 
+// IsExternalReference returns true if this is a reference to an external file.
+// External refs have the format: file.yaml#/path/to/schema
+func (d *SchemaDescriptor) IsExternalReference() bool {
+	if d.Ref == "" {
+		return false
+	}
+	// External refs contain # but don't start with it
+	return !strings.HasPrefix(d.Ref, "#") && strings.Contains(d.Ref, "#")
+}
+
+// ParseExternalRef splits an external reference into its file path and internal path.
+// For "common/api.yaml#/components/schemas/Pet", returns ("common/api.yaml", "#/components/schemas/Pet").
+// Returns empty strings if not an external ref.
+func (d *SchemaDescriptor) ParseExternalRef() (filePath, internalPath string) {
+	if !d.IsExternalReference() {
+		return "", ""
+	}
+	parts := strings.SplitN(d.Ref, "#", 2)
+	if len(parts) != 2 {
+		return "", ""
+	}
+	return parts[0], "#" + parts[1]
+}
+
 // IsComponentSchema returns true if this schema is defined in #/components/schemas
 func (d *SchemaDescriptor) IsComponentSchema() bool {
 	return len(d.Path) >= 2 && d.Path[0] == "components" && d.Path[1] == "schemas"

experimental/internal/codegen/test/comprehensive/output/comprehensive.gen.go

@@ -0,0 +1,5 @@
+package: externalref
+output: internal/codegen/test/external_ref/spec.gen.go
+import-mapping:
+  ./packagea/spec.yaml: github.com/oapi-codegen/oapi-codegen/experimental/internal/codegen/test/external_ref/packagea
+  ./packageb/spec.yaml: github.com/oapi-codegen/oapi-codegen/experimental/internal/codegen/test/external_ref/packageb