Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions document_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -2600,3 +2600,36 @@ func TestDocument_BuildV3Model_NoVersionNode(t *testing.T) {
require.Error(t, buildErr)
assert.Contains(t, buildErr.Error(), "no openapi version/tag found")
}

func TestDocument_BuildV3Model_RefInSchemaInstanceValue(t *testing.T) {
spec := `openapi: 3.1.0
info: {title: Instance values, version: "1"}
paths: {}
components:
schemas:
Data:
type: object
enum:
- {$ref: '#/nope'}
const: {$ref: 'gone.yaml#/x'}
default: {$ref: '#/components/schemas/Target'}
examples:
- {$ref: '#/nope'}
Target:
type: string
`
doc, err := NewDocument([]byte(spec))
require.NoError(t, err)
model, err := doc.BuildV3Model()
require.NoError(t, err)

schema := model.Model.Components.Schemas.GetOrZero("Data").Schema()
var def map[string]string
require.NoError(t, schema.Default.Decode(&def))
assert.Equal(t, map[string]string{"$ref": "#/components/schemas/Target"}, def, "default is data and is not inlined")
var con map[string]string
require.NoError(t, schema.Const.Decode(&con))
assert.Equal(t, map[string]string{"$ref": "gone.yaml#/x"}, con)
require.Len(t, schema.Enum, 1)
require.Len(t, schema.Examples, 1)
}
42 changes: 41 additions & 1 deletion index/extract_refs.go
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,16 @@ func isOpenAPIExampleKeywordSegment(seenPath []string, idx int) bool {
if seenPath[idx] != "example" && seenPath[idx] != "examples" {
return false
}
return isOpenAPIKeywordSegment(seenPath, idx)
}

// isOpenAPIKeywordSegment reports whether seenPath[idx] is a field name rather than a name the
// document chose: a component, property, response code or Example Object name. A property named
// "default" or a response keyed "default" is a name; the "default" field of a schema is not.
func isOpenAPIKeywordSegment(seenPath []string, idx int) bool {
if idx < 0 || idx >= len(seenPath) {
return false
}
// A component or schema name cannot itself introduce another named map.
// For example, properties/definitions/example ends at a payload keyword.
nameSlot := false
Expand All @@ -71,13 +81,43 @@ func isOpenAPIExampleKeywordSegment(seenPath []string, idx int) bool {
}
switch segment {
case "properties", "patternProperties", "definitions", "$defs", "dependentSchemas",
"headers", "links", "callbacks", "encoding", "webhooks":
"headers", "links", "callbacks", "encoding", "webhooks", "responses", "examples":
nameSlot = true
case "parameters":
// Swagger 2.0 keeps reusable parameters in a root map. Elsewhere it is an array.
nameSlot = i == 0
}
}
return !nameSlot
}

// underSchemaInstanceValuePath reports whether path, the location of node, is inside a value
// JSON Schema treats as instance data: the value of enum, const or default, or the examples array.
// A $ref key there is part of the data, not a reference. An OpenAPI examples field is a map of
// Example Objects, so examples counts only when it holds an array. The resolver marks array
// elements with "[]"; the index walk does not, so node, when not nil, is the value at path.
func underSchemaInstanceValuePath(path []string, node *yaml.Node) bool {
for i, segment := range path {
switch segment {
case "enum", "const", "default":
case "examples":
if i+1 < len(path) {
if path[i+1] != "[]" {
continue
}
} else if node == nil || !utils.IsNodeArray(node) {
continue
}
default:
continue
}
if isOpenAPIKeywordSegment(path, i) {
return true
}
}
return false
}

// underOpenAPIExamplePayloadPath reports whether seenPath points to raw example payload content.
// A bare `example` path is not payload by itself because libopenapi still supports a direct
// `$ref` wrapper there for bundling. Once traversal moves below `example`, or into an Example
Expand Down
2 changes: 1 addition & 1 deletion index/extract_refs_ref.go
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ func (index *SpecIndex) extractReferenceAt(
if len(node.Content) <= keyIndex+1 {
return nil
}
if underOpenAPIExamplePayloadPath(seenPath) {
if underOpenAPIExamplePayloadPath(seenPath) || underSchemaInstanceValuePath(seenPath, nil) {
return nil
}

Expand Down
130 changes: 130 additions & 0 deletions index/extract_refs_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -1270,3 +1270,133 @@ components:
}
}
}

func TestUnderSchemaInstanceValuePath(t *testing.T) {
var seq, mapping yaml.Node
require.NoError(t, yaml.Unmarshal([]byte("[{$ref: '#/a'}]"), &seq))
require.NoError(t, yaml.Unmarshal([]byte("{named: {$ref: '#/a'}}"), &mapping))
tests := []struct {
name string
path []string
node *yaml.Node
want bool
}{
{"empty", nil, nil, false},
{"enum", []string{"components", "schemas", "S", "enum"}, nil, true},
{"const", []string{"components", "schemas", "S", "const"}, nil, true},
{"default", []string{"components", "schemas", "S", "default"}, nil, true},
{"below_default", []string{"components", "schemas", "S", "default", "nested"}, nil, true},
{"items_enum", []string{"components", "schemas", "S", "items", "enum"}, nil, true},
{"examples_array", []string{"components", "schemas", "S", "examples"}, seq.Content[0], true},
{"examples_array_element", []string{"components", "schemas", "S", "examples", "[]"}, nil, true},
{"examples_map", []string{"content", "application/json", "examples"}, mapping.Content[0], false},
{"examples_unknown_node", []string{"components", "schemas", "S", "examples"}, nil, false},
{"example_object_named_default", []string{"content", "application/json", "examples", "default"}, nil, false},
{"schema_named_default", []string{"components", "schemas", "default"}, nil, false},
{"property_named_default", []string{"components", "schemas", "S", "properties", "default"}, nil, false},
{"property_named_enum", []string{"components", "schemas", "S", "properties", "enum"}, nil, false},
{"property_named_const", []string{"components", "schemas", "S", "properties", "const"}, nil, false},
{"default_response", []string{"paths", "~1pets", "get", "responses", "default"}, nil, false},
{"default_of_property_named_default", []string{"components", "schemas", "S", "properties", "default", "default"}, nil, true},
{"swagger_parameter_named_default", []string{"parameters", "default"}, nil, false},
{"operation_parameter_schema_default", []string{"paths", "~1pets", "get", "parameters", "schema", "default"}, nil, true},
{"default_response_schema_default", []string{"paths", "~1pets", "get", "responses", "default", "content", "application/json", "schema", "default"}, nil, true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
assert.Equal(t, tt.want, underSchemaInstanceValuePath(tt.path, tt.node))
})
}
}

func TestExtractReferenceAt_IgnoresRefsInsideSchemaInstanceValues(t *testing.T) {
idx := NewTestSpecIndex().Load().(*SpecIndex)
idx.specAbsolutePath = "test.yaml"

var refNode yaml.Node
_ = yaml.Unmarshal([]byte(`$ref: '#/components/schemas/Pet'`), &refNode)

ref := idx.extractReferenceAt(refNode.Content[0], nil, 0, []string{"components", "schemas", "S", "default"}, nil, false, "")
assert.Nil(t, ref)
assert.Empty(t, idx.GetAllReferences())
assert.Empty(t, idx.GetAllSequencedReferences())
}

func TestSpecIndex_ExtractRefs_SchemaInstanceValueRefsIgnored(t *testing.T) {
spec := `openapi: 3.1.0
info:
title: Instance values
version: 1.0.0
paths:
/pets:
get:
responses:
default:
$ref: '#/components/responses/Default'
"200":
description: ok
content:
application/json:
schema:
type: object
default: {$ref: '#/data/response-default'}
examples:
default:
$ref: '#/components/examples/Default'
components:
responses:
Default:
description: default
examples:
Default:
value: {ok: true}
schemas:
Data:
type: object
enum:
- {$ref: '#/data/enum'}
const: {$ref: '#/data/const'}
default:
nested: {$ref: '#/data/default'}
examples:
- {$ref: '#/data/examples'}
items:
enum: [{$ref: '#/data/items-enum'}]
Named:
type: object
properties:
default: {$ref: '#/components/schemas/Target'}
enum: {$ref: '#/components/schemas/Target'}
const: {$ref: '#/components/schemas/Target'}
examples: {$ref: '#/components/schemas/Target'}
default:
$ref: '#/components/schemas/Target'
Target:
type: string
`

var rootNode yaml.Node
require.NoError(t, yaml.Unmarshal([]byte(spec), &rootNode))

idx := NewSpecIndexWithConfig(&rootNode, CreateOpenAPIIndexConfig())

rawRefs := make(map[string]bool)
for _, ref := range idx.GetRawReferencesSequenced() {
rawRefs[ref.RawRef] = true
}

assert.True(t, rawRefs["#/components/responses/Default"], "a response keyed default is a reference")
assert.True(t, rawRefs["#/components/examples/Default"], "an Example Object named default is a reference")
assert.True(t, rawRefs["#/components/schemas/Target"], "properties named default, enum, const and examples are schemas")
for raw := range rawRefs {
assert.False(t, strings.HasPrefix(raw, "#/data/"), "instance data indexed as a reference: %s", raw)
}
assert.Empty(t, idx.GetReferenceIndexErrors())
}

func TestIsOpenAPIKeywordSegment_OutOfRange(t *testing.T) {
path := []string{"components", "schemas", "S", "default"}
assert.False(t, isOpenAPIKeywordSegment(path, -1))
assert.False(t, isOpenAPIKeywordSegment(path, len(path)))
assert.True(t, isOpenAPIKeywordSegment(path, 3))
}
3 changes: 3 additions & 0 deletions index/extract_refs_walk.go
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,9 @@ func (index *SpecIndex) walkChildExtractRefs(node, parent *yaml.Node, state *ext
if isDirectOpenAPIExampleValuePath(state.seenPath) && !isDirectOpenAPIExampleRefNode(node) {
return nil
}
if underSchemaInstanceValuePath(state.seenPath, node) {
return nil
}
state.level++
if isPoly, _ := index.checkPolymorphicNode(state.prev); isPoly {
state.poly = true
Expand Down
14 changes: 14 additions & 0 deletions index/resolver_relatives.go
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,9 @@ func (resolver *Resolver) extractRelativesWithState(
if isDirectOpenAPIExampleValuePath(walkPath) && !isDirectOpenAPIExampleRefNode(node) {
return nil
}
if underSchemaInstanceValuePath(walkPath, node) {
return nil
}
// Guard against stack overflow from deeply nested or circular specs.
// Journey tracks the reference chain (100 max); depth tracks recursive calls (500 max).
if len(state.journey) > 100 {
Expand All @@ -92,6 +95,13 @@ func (resolver *Resolver) extractRelativesWithState(
childPath := walkPath
if node.Kind == yaml.MappingNode && i%2 == 1 {
childPath = append(walkPath, node.Content[i-1].Value)
// The index does not extract references under excluded extensions, so the
// resolver must not look for them there either. A property named x-... is
// still a schema.
if resolver.excludeExtensionRefs() && strings.HasPrefix(childPath[len(childPath)-1], "x-") &&
isOpenAPIKeywordSegment(childPath, len(childPath)-1) {
continue
}
} else if node.Kind == yaml.SequenceNode {
childPath = append(walkPath, "[]")
}
Expand Down Expand Up @@ -119,6 +129,10 @@ func (resolver *Resolver) extractRelativesWithState(
return found
}

func (resolver *Resolver) excludeExtensionRefs() bool {
return resolver.specIndex != nil && resolver.specIndex.config != nil && resolver.specIndex.config.ExcludeExtensionRefs
}

func (resolver *Resolver) handleRelativeDepthLimit(ref *Reference, state relativeWalkState) []*Reference {
def := "unknown"
if ref != nil {
Expand Down
65 changes: 65 additions & 0 deletions index/resolver_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -2089,3 +2089,68 @@ func TestResolverDeepExamplePaths(t *testing.T) {
require.Len(t, found, 1)
require.Equal(t, "#/components/schemas/Target", found[0].Definition)
}

func TestResolver_SchemaInstanceValueRefsNotResolved(t *testing.T) {
spec := `openapi: 3.1.0
components:
schemas:
Data:
type: object
enum:
- {$ref: '#/missing/enum'}
const: {$ref: 'missing.yaml#/const'}
default:
nested: {$ref: '#/missing/default'}
examples:
- {$ref: '#/missing/examples'}
properties:
default: {$ref: '#/components/schemas/Target'}
Target:
type: string
`
var root yaml.Node
require.NoError(t, yaml.Unmarshal([]byte(spec), &root))
idx := NewSpecIndexWithConfig(&root, CreateOpenAPIIndexConfig())
ref, _ := idx.SearchIndexForReference("#/components/schemas/Data")
require.NotNil(t, ref)
found := NewResolver(idx).extractRelatives(ref, ref.Node, nil, map[string]bool{}, nil, false, 0, "")
require.Len(t, found, 1, "only the property named default is a reference")
require.Equal(t, "#/components/schemas/Target", found[0].Definition)

require.Empty(t, NewResolver(idx).Resolve())
}

func TestResolver_ExcludeExtensionRefs(t *testing.T) {
spec := `openapi: 3.1.0
components:
schemas:
Pasta:
type: object
x-hello:
thing: {$ref: 'gone.yaml#/x'}
properties:
x-name: {$ref: '#/components/schemas/Target'}
Target:
type: string
`
for _, exclude := range []bool{false, true} {
t.Run(fmt.Sprintf("exclude=%v", exclude), func(t *testing.T) {
var root yaml.Node
require.NoError(t, yaml.Unmarshal([]byte(spec), &root))
c := CreateOpenAPIIndexConfig()
c.ExcludeExtensionRefs = exclude
idx := NewSpecIndexWithConfig(&root, c)
ref, _ := idx.SearchIndexForReference("#/components/schemas/Pasta")
require.NotNil(t, ref)
resolver := NewResolver(idx)
found := resolver.extractRelatives(ref, ref.Node, nil, map[string]bool{}, nil, false, 0, "")
require.Len(t, found, 1, "a property named x-name is a schema")
require.Equal(t, "#/components/schemas/Target", found[0].Definition)
if exclude {
require.Empty(t, resolver.resolvingErrors)
} else {
require.Len(t, resolver.resolvingErrors, 1)
}
})
}
}
Loading