Closed mzielinski closed 7 months ago
The intention behind @OpenApiExample(object = {})
is to attach an example in-place, for e.g. unknown types or this particular use-case (different examples in e.g. request body & in generic entity scheme description), so it's not leaked to referenced types. Thanks to that, we can provide such formats for e.g. Object
type:
// should contain inline object example
@OpenApiExample(objects = {
@OpenApiExampleProperty(name = "name", value = "Margot Robbie"),
@OpenApiExampleProperty(name = "link", value = "https://www.youtube.com/watch?v=dQw4w9WgXcQ")
})
public @NotNull Object getInlinedExampleObject() {
return new String[] { timestamp };
}
results in:
"inlinedExampleObject" : {
"type" : "object",
"example" : {
"name" : "Margot Robbie",
"link" : "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
}
And this:
// should contain object example
@OpenApiExample(objects = {
@OpenApiExampleProperty(name = "Barbie", objects = {
@OpenApiExampleProperty(name = "name", value = "Margot Robbie"),
@OpenApiExampleProperty(name = "link", value = "https://www.youtube.com/watch?v=dQw4w9WgXcQ")
}),
})
public @NotNull Object[] getExampleObjects() {
return new String[] { timestamp };
}
results in:
"exampleObjects" : {
"type" : "array",
"items" : {
"type" : "object"
},
"example" : {
"Barbie" : {
"name" : "Margot Robbie",
"link" : "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
}
},
If we know the type tho, such as your Barbie
type, and we want to define global example for specific fields, it should be specified directly on properties within this type, like here:
So in the referenced object:
"foos" : {
"type" : "array",
"items" : {
"$ref" : "#/components/schemas/Foo"
}
},
we can see these dedicated examples:
"Foo" : {
"type" : "object",
"additionalProperties" : false,
"properties" : {
"property" : {
"type" : "string"
},
"link" : {
"type" : "string",
"example" : "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
}
},
As far as I understand, you'd like to achieve a similar result by enforcing @OpenApiExample
to override examples in referenced entities. If that's correct, then I see 3 issues:
I've updated the example to cover this with cases we were talking about:
That returns:
"exampleFoo" : {
"$ref" : "#/components/schemas/Foo",
"example" : {
"name" : "Margot Robbie",
"link" : "Dedicated link"
}
},
"exampleObject" : {
"type" : "object",
"example" : {
"name" : "Margot Robbie",
"link" : "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
},
"exampleObjects" : {
"type" : "array",
"items" : {
"type" : "object"
},
"example" : {
"Barbie" : {
"name" : "Margot Robbie",
"link" : "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
}
},
and unaffected example (as expected) in the Foo scheme:
"Foo" : {
"type" : "object",
"additionalProperties" : false,
"properties" : {
"link" : {
"type" : "string",
"example" : "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
}
},
If I missed the point, just let me know.
It is clear. Thank you for adding additional test, and explaining about the issues.
Actual behavior (the bug)
With such configuration, at the end I do not see my examples in the OpenAPI specification
Specification which is generated is
Expected behavior
I would expect, that example should be injected to the openapi description like
So specification code generated should be more like
Additional context
Currently, when I change type to Barbie[] (the same as we have in existing example Object[]), then it is properly injected example, but it requires to change specification, what it not acceptable.