swagger-api / swagger-api/swagger-core
[Bug]: SpecFilter skips the ApiResponse#$ref field
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 7.5k
- Forks
- 2.3k
- Avg merge
- 18h 1m
- Merged PRs (30d)
- 10
Description
Description of the problem/issue
When Spring's OpenApiHateoasLinksCustomizer calls the SpecFilter#removeBrokenReferenceDefinitions method, SpecFilter doesn't take into account the "$ref" field of the ApiResponse class:
addPathItemSchemaRef:
...
for (String keyResponses : op.getResponses().keySet()) {
ApiResponse response = op.getResponses().get(keyResponses);
if (response.getHeaders() != null) {
for (String keyHeaders : response.getHeaders().keySet()) {
Header header = response.getHeaders().get(keyHeaders);
addSchemaRef(header.getSchema(), referencedDefinitions);
addContentSchemaRef(header.getContent(), referencedDefinitions);
}
}
addContentSchemaRef(response.getContent(), referencedDefinitions);
}
...
private void addContentSchemaRef(Content content, Set<String> referencedDefinitions) {
if (content != null) {
for (MediaType mediaType : content.values()) {
addSchemaRef(mediaType.getSchema(), referencedDefinitions);
}
}
}
Affected Version
2.2.22
Earliest version the bug appears in (if known):
2.2.22
Steps to Reproduce
Define a controller with a reference to a custom schema like so:
@Operation(summary = "Finds one sample", responses = {
@ApiResponse(responseCode = "404", ref = "MyCustomSchema"),
})
Add your custom schema and response using OpenApiCustomizer like so:
protected static final String REF_MY_CUSTOM_SCHEMA = constructRef("MyCustomSchema");
@Bean
OpenApiCustomizer openApiCustomizer() {
return openApi -> {
var components = ofNullable(openApi.getComponents()).orElseGet(Components::new);
commonResponses().forEach(components::addResponses);
commonSchemas().forEach(components::addSchemas);
openApi.setComponents(components);
};
}
protected Map<String, Schema> commonSchemas() {
return ModelConverters.getInstance().read(MyCustomSchema.class);
}
protected Map<String, ApiResponse> commonResponses() {
return Map.of(
"MyCustomSchema", new ApiResponse()
.description("A custom response")
.content(new Content().addMediaType(APPLICATION_JSON_VALUE, mediaTypeOf(REF_MY_CUSTOM_SCHEMA)))
);
}
private static MediaType mediaTypeOf(String simpleRef) {
return new MediaType().schema(new Schema<>().$ref(simpleRef));
}
Expected Behavior
The schema is presented in the resulting JSON
Actual Behavior
The schema gets filtered by the SpecFilter
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at SpecFilter#removeBrokenReferenceDefinitions, especially the response handling shown in the issue, and inspect how ApiResponse references are collected. Reproduce the controller and OpenApiCustomizer setup from the report, then verify that the resulting JSON retains the schema referenced through ApiResponse#$ref instead of filtering it.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, spring
- Domain
- api
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100