openapi3: resolve refs in parameter examples

openapi3/example_refs_test.go

@@ -0,0 +1,80 @@
+package openapi3_test
+
+import (
+	"testing"
+
+	"github.com/getkin/kin-openapi/openapi3"
+	"github.com/stretchr/testify/require"
+)
+
+func TestParameterExampleRef(t *testing.T) {
+	loader := openapi3.NewLoader()
+	doc, err := loader.LoadFromFile("testdata/example_refs.yml")
+	require.NoError(t, err)
+	err = doc.Validate(loader.Context)
+	require.NoError(t, err)
+	param := doc.Paths.Value("/test").Post.Parameters[0].Value
+	require.NotNil(t, param, "Parameter should not be nil")
+	require.NotNil(t, param.Examples["Test"].Value, "Parameter example should not be nil")
+	require.Equal(t, "An example", param.Examples["Test"].Value.Summary)
+}
+
+func TestParameterExampleWithContentRef(t *testing.T) {
+	loader := openapi3.NewLoader()
+	doc, err := loader.LoadFromFile("testdata/example_refs.yml")
+	require.NoError(t, err)
+	err = doc.Validate(loader.Context)
+	require.NoError(t, err)
+	param := doc.Paths.Value("/test").Post.Parameters[1].Value
+	require.NotNil(t, param, "Parameter should not be nil")
+	require.NotNil(t, param.Content["application/json"].Examples["Test"].Value, "Parameter example should not be nil")
+	require.Equal(t, "An example", param.Content["application/json"].Examples["Test"].Value.Summary)
+}
+
+func TestRequestBodyExampleRef(t *testing.T) {
+	loader := openapi3.NewLoader()
+	doc, err := loader.LoadFromFile("testdata/example_refs.yml")
+	require.NoError(t, err)
+	err = doc.Validate(loader.Context)
+	require.NoError(t, err)
+	requestBody := doc.Paths.Value("/test").Post.RequestBody.Value
+	require.NotNil(t, requestBody, "Request body should not be nil")
+	require.NotNil(t, requestBody.Content["application/json"].Examples["Test"].Value, "Request body example should not be nil")
+	require.Equal(t, "An example", requestBody.Content["application/json"].Examples["Test"].Value.Summary)
+}
+
+func TestResponseExampleRef(t *testing.T) {
+	loader := openapi3.NewLoader()
+	doc, err := loader.LoadFromFile("testdata/example_refs.yml")
+	require.NoError(t, err)
+	err = doc.Validate(loader.Context)
+	require.NoError(t, err)
+	response := doc.Paths.Value("/test").Post.Responses.Value("200").Value
+	require.NotNil(t, response, "Response should not be nil")
+	require.NotNil(t, response.Content["application/json"].Examples["Test"].Value, "Response example should not be nil")
+	require.Equal(t, "An example", response.Content["application/json"].Examples["Test"].Value.Summary)
+}
+
+func TestHeaderExampleRef(t *testing.T) {
+	loader := openapi3.NewLoader()
+	doc, err := loader.LoadFromFile("testdata/example_refs.yml")
+	require.NoError(t, err)
+	err = doc.Validate(loader.Context)
+	require.NoError(t, err)
+	response := doc.Paths.Value("/test").Post.Responses.Value("200").Value
+	header := response.Headers["X-Test-Header"].Value
+	require.NotNil(t, header, "Header should not be nil")
+	require.NotNil(t, header.Examples["Test"].Value, "Header example should not be nil")
+	require.Equal(t, "An example", header.Examples["Test"].Value.Summary)
+}
+
+func TestComponentExampleRef(t *testing.T) {
+	loader := openapi3.NewLoader()
+	doc, err := loader.LoadFromFile("testdata/example_refs.yml")
+	require.NoError(t, err)
+	err = doc.Validate(loader.Context)
+	require.NoError(t, err)
+	example := doc.Components.Examples["RefExample"].Value
+	require.NotNil(t, example, "Example should not be nil")
+	require.Equal(t, "An example", example.Summary)
+}

openapi3/loader.go

@@ -657,6 +657,11 @@ func (loader *Loader) resolveHeaderRef(doc *T, component *HeaderRef, documentPat
 			return err
 		}
 	}
+	for _, example := range value.Examples {
+		if err := loader.resolveExampleRef(doc, example, documentPath); err != nil {
+			return err
+		}
+	}
 	return nil
 }
 
@@ -716,12 +721,22 @@ func (loader *Loader) resolveParameterRef(doc *T, component *ParameterRef, docum
 				return err
 			}
 		}
+		for _, example := range contentType.Examples {
+			if err := loader.resolveExampleRef(doc, example, documentPath); err != nil {
+				return err
+			}
+		}
 	}
 	if schema := value.Schema; schema != nil {
 		if err := loader.resolveSchemaRef(doc, schema, documentPath, []string{}); err != nil {
 			return err
 		}
 	}
+	for _, example := range value.Examples {
+		if err := loader.resolveExampleRef(doc, example, documentPath); err != nil {
+			return err
+		}
+	}
 	return nil
 }
 

openapi3/testdata/example_refs.yml

@@ -0,0 +1,72 @@
+openapi: 3.0.3
+info:
+  title: Test API
+  version: 1.0.0
+paths:
+  /test:
+    post:
+      summary: Test endpoint
+      parameters:
+        - $ref: '#/components/parameters/TestParameter'
+        - $ref: '#/components/parameters/TestParameterWithContent'
+      requestBody:
+        $ref: '#/components/requestBodies/TestBody'
+      responses:
+        '200':
+          $ref: '#/components/responses/TestResponse'
+components:
+  examples:
+    TestExample:
+      summary: An example
+      value: 'hello'
+    RefExample:
+      $ref: '#/components/examples/TestExample'
+  headers:
+    TestHeader:
+      description: A test header
+      schema:
+        type: string
+      examples:
+        Test:
+          $ref: '#/components/examples/TestExample'
+  parameters:
+    TestParameter:
+      name: test
+      in: query
+      schema:
+        type: string
+      examples:
+        Test:
+          $ref: '#/components/examples/TestExample'
+    TestParameterWithContent:
+      name: testContent
+      in: query
+      content:
+        application/json:
+          schema:
+            type: string
+          examples:
+            Test:
+              $ref: '#/components/examples/TestExample'
+  requestBodies:
+    TestBody:
+      content:
+        application/json:
+          schema:
+            type: string
+          examples:
+            Test:
+              $ref: '#/components/examples/TestExample'
+  responses:
+    TestResponse:
+      description: A test response
+      headers:
+        X-Test-Header:
+          $ref: '#/components/headers/TestHeader'
+      content:
+        application/json:
+          schema:
+            type: string
+          examples:
+            Test:
+              $ref: '#/components/examples/TestExample'