feat(openapi): allow external $refs (#26)

Author: acsauk

external/manager.go

@@ -2,19 +2,20 @@ package external
 
 import (
 	"fmt"
+	"os"
+	"os/exec"
+	"path"
+	"path/filepath"
+	"slices"
+	"strings"
+
 	"github.com/hashicorp/go-hclog"
 	goplugin "github.com/hashicorp/go-plugin"
 	"github.com/imposter-project/imposter-go/external/shared"
 	"github.com/imposter-project/imposter-go/internal/config"
 	"github.com/imposter-project/imposter-go/internal/version"
 	"github.com/imposter-project/imposter-go/pkg/logger"
 	"gopkg.in/yaml.v3"
-	"os"
-	"os/exec"
-	"path"
-	"path/filepath"
-	"slices"
-	"strings"
 )
 
 var pluginMap map[string]goplugin.Plugin

internal/config/multi_document_test.go

@@ -36,6 +36,8 @@ resources:
 			name: "multiple documents with OpenAPI and SwaggerUI",
 			yamlContent: `plugin: openapi
 specFile: api.json
+config:
+  externalBaseURL: "http://example.com"
 resources:
   - path: /pets
     method: GET
@@ -58,6 +60,16 @@ config:
 				if configs[0].SpecFile != "api.json" {
 					t.Errorf("Expected specFile 'api.json', got '%s'", configs[0].SpecFile)
 				}
+
+				// Verify plugin config content can be unmarshalled
+				var plugin0Config map[string]interface{}
+				if err := configs[0].PluginConfig.Decode(&plugin0Config); err != nil {
+					t.Errorf("Failed to unmarshal plugin config: %v", err)
+				}
+
+				if plugin0Config["externalBaseURL"] != "http://example.com" {
+					t.Errorf("Expected externalBaseURL 'http://example.com', got '%v'", plugin0Config["externalBaseURL"])
+				}
 				if len(configs[0].Resources) != 1 {
 					t.Errorf("Expected 1 resource in first config, got %d", len(configs[0].Resources))
 				}
@@ -73,13 +85,13 @@ config:
 				}
 
 				// Verify plugin config content can be unmarshaled
-				var pluginConfig map[string]interface{}
-				if err := configs[1].PluginConfig.Decode(&pluginConfig); err != nil {
+				var plugin1Config map[string]interface{}
+				if err := configs[1].PluginConfig.Decode(&plugin1Config); err != nil {
 					t.Errorf("Failed to unmarshal plugin config: %v", err)
 				}
 
-				if specUrl, ok := pluginConfig["specUrl"].(string); !ok || specUrl != "http://localhost:8080/system/openapi" {
-					t.Errorf("Expected specUrl 'http://localhost:8080/system/openapi', got '%v'", pluginConfig["specUrl"])
+				if specUrl, ok := plugin1Config["specUrl"].(string); !ok || specUrl != "http://localhost:8080/system/openapi" {
+					t.Errorf("Expected specUrl 'http://localhost:8080/system/openapi', got '%v'", plugin1Config["specUrl"])
 				}
 			},
 		},

plugin/openapi/openapi.go

@@ -2,17 +2,20 @@ package openapi
 
 import (
 	"fmt"
+	"net/http"
+	"net/url"
+	"os"
+	"sort"
+	"strings"
+
 	"github.com/imposter-project/imposter-go/internal/config"
 	"github.com/imposter-project/imposter-go/internal/exchange"
 	"github.com/imposter-project/imposter-go/pkg/logger"
 	"github.com/pb33f/libopenapi"
 	validator "github.com/pb33f/libopenapi-validator"
 	"github.com/pb33f/libopenapi-validator/errors"
+	"github.com/pb33f/libopenapi/datamodel"
 	"github.com/pb33f/libopenapi/datamodel/high/base"
-	"net/http"
-	"os"
-	"sort"
-	"strings"
 )
 
 // OpenAPIVersion represents the version of OpenAPI being used
@@ -46,7 +49,8 @@ type Operation struct {
 }
 
 type parserOptions struct {
-	stripServerPath bool
+	stripServerPath          bool
+	externalReferenceBaseURL string
 }
 
 type OpenAPIParser interface {
@@ -80,6 +84,17 @@ func newOpenAPIParser(specFile string, validate bool, opts parserOptions) (OpenA
 		return nil, fmt.Errorf("cannot create new document: %e", err)
 	}
 
+	if opts.externalReferenceBaseURL != "" {
+		u, err := url.Parse(opts.externalReferenceBaseURL)
+		if err != nil {
+			return nil, fmt.Errorf("cannot parse external reference URL: %e", err)
+		}
+
+		document.SetConfiguration(&datamodel.DocumentConfiguration{BaseURL: u})
+
+		logger.Infof("external base URL set to: %s", u.String())
+	}
+
 	var oasValidator *validator.Validator
 	if validate {
 		highLevelValidator, validatorErrs := validator.NewValidator(document)

plugin/openapi/parser_test.go

@@ -1,6 +1,8 @@
 package openapi
 
 import (
+	"net/http"
+	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"testing"
@@ -63,3 +65,50 @@ func TestNewOpenAPIParser(t *testing.T) {
 		})
 	}
 }
+
+func TestOpenAPIParser_ExternalURLRefsAreParsed(t *testing.T) {
+	schemaJSON := `{
+	  "User": {
+		"properties": {
+		  "id": {
+			"type": "integer",
+			"format": "int64",
+			"example": 10
+		  },
+		  "username": {
+			"type": "string",
+			"example": "theUser"
+		  },
+		  "firstName": {
+			"type": "string",
+			"example": "John"
+		  },
+		  "lastName": {
+			"type": "string",
+			"example": "James"
+		  }
+		}
+	  }
+	}`
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/schemas/user.json" {
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(schemaJSON))
+			return
+		}
+		http.NotFound(w, r)
+	}))
+	defer ts.Close()
+
+	workingDir, _ := os.Getwd()
+	specFile := filepath.Join(workingDir, "testdata/externalRef/users.yaml")
+
+	parser, err := newOpenAPIParser(specFile, false, parserOptions{
+		externalReferenceBaseURL: ts.URL + "/",
+	})
+
+	assert.NoError(t, err)
+	assert.NotNil(t, parser)
+	assert.Equal(t, OpenAPI30, parser.GetVersion())
+	assert.Len(t, parser.GetOperations(), 2)
+}

plugin/openapi/plugin.go

@@ -2,6 +2,7 @@ package openapi
 
 import (
 	"fmt"
+
 	"github.com/imposter-project/imposter-go/plugin/rest"
 
 	"github.com/imposter-project/imposter-go/internal/config"
@@ -26,6 +27,16 @@ func NewPluginHandler(cfg *config.Config, imposterConfig *config.ImposterConfig)
 	opts := parserOptions{
 		stripServerPath: cfg.StripServerPath,
 	}
+
+	if !cfg.PluginConfig.IsZero() {
+		var pluginConfig map[string]interface{}
+		if err := cfg.PluginConfig.Decode(&pluginConfig); err != nil {
+			return nil, fmt.Errorf("failed to unmarshal plugin config: %w", err)
+		}
+
+		opts.externalReferenceBaseURL = pluginConfig["externalBaseURL"].(string)
+	}
+
 	validate := cfg.Validation != nil && (cfg.Validation.IsRequestValidationEnabled() || cfg.Validation.IsResponseValidationEnabled())
 	parser, err := newOpenAPIParser(specFile, validate, opts)
 	if err != nil {

plugin/openapi/testdata/externalRef/imposter-config.yaml

@@ -0,0 +1,11 @@
+plugin: openapi
+specFile: users-external-ref.yaml
+
+config:
+  externalBaseURL: http://example.com
+
+resources:
+  - path: /users
+    method: GET
+    response:
+      statusCode: 200

plugin/openapi/testdata/externalRef/users.yaml

@@ -0,0 +1,44 @@
+openapi: 3.0.2
+info:
+  title: External URL references test
+  description: A test document
+  version: 1.0.0
+paths:
+  /users:
+    get:
+      summary: Get all users
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: 'http://example.com/schemas/user.json'
+  /users/{id}:
+    get:
+      summary: Get a user
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+
+components:
+  schemas:
+    User:
+      properties:
+        id:
+          type: integer
+          format: int64
+          example: 10
+        username:
+          type: string
+          example: theUser
+        firstName:
+          type: string
+          example: John
+        lastName:
+          type: string
+          example: James

tools/validate_config/current-format-schema.json

@@ -17,6 +17,9 @@
                     "description": "OpenAPI specification file (YAML or JSON)",
                     "type": "string"
                 },
+                "externalBaseURL": {
+                    "type": "string"
+                },
                 "wsdlFile": {
                     "type": "string"
                 },
@@ -83,6 +86,14 @@
                 },
                 "validation": { "$ref": "shared-definitions.json#/definitions/validation" }
             },
+            "if": {
+                "plugin": {
+                    "type": { "const": "openapi" }
+                }
+            },
+            "then": {
+                "required": ["specFile"]
+            },
             "additionalProperties": false
         }
     }