I have a Spring Boot Project with springfox-swagger2
2.7.0
And I have the following controller:
@Api(tags = { "Some" }, description = "CRUD for Some Stuff")
@RestController
@RequestMapping(path = "/some")
public class SomeController {
@ApiOperation(value = "Get some")
@GetMapping(value = "{someId}", produces = MediaType.APPLICATION_JSON_VALUE)
public Response getSomeById(@PathVariable("someId") Id someId) {
return ...;
}
...
}
I want to control what is displayed in the docs by annotating the Id
class, and this is working only for some parts of the annotation, but not all.
The Id
class (which has a registered converter from String
to Id
):
public class Id {
@ApiParam(value = "This is the description", defaultValue = "1f1f1f",required = true, name = "someId", type = "string")
private final Long id;
public Id(Long id) {
this.id = id;
}
public Long getId() {
return id;
}
}
Now the Swagger JSON
returned looks as follows:
"parameters":[{
"name":"id",
"in":"query",
"description":"This is the description",
"required":true,
"type":"integer",
"default":"1f1f1f",
"format":"int64"
}]
My question (or possibly bug report) is: why are some parts of the @ApiParam
annotation used (like value
, defaultValue
and required
), but others aren't, like name
and type
?
Why does it seem like I cannot change the name
or type
here?
For my particular use case, the latter is the one I would want to change to string
.
Update
I've settled on adding the following component with the help from skadya.
@Component
public class OverrideSwaggerApiParamBuilder implements
ExpandedParameterBuilderPlugin {
@Override
public boolean supports(DocumentationType type) {
return DocumentationType.SWAGGER_2 == type;
}
@Override
public void apply(ParameterExpansionContext context) {
Optional<ApiParam> apiParamOptional = findApiParamAnnotation(context.getField().getRawMember());
if (apiParamOptional.isPresent()) {
ApiParam param = apiParamOptional.get();
context.getParameterBuilder()
.name(param.name())
.modelRef(new ModelRef(param.type()))
.build();
}
}
}
The Authors of springfox feel this could be a bug: https://github.com/springfox/springfox/issues/2107
By default, @ApiParam attribute 'name' and 'type' are used to override the parameter name and detected type of direct parameters specified in the API method. When you use @ApiParam on an field, the type and name are deduced by the field's name and its declared type and overriden value for name and type are not considered. (It looks by design in springfox, you may have a look at implementation springfox.documentation.swagger.readers.parameter.SwaggerExpandedParameterBuilder
)
If you still wish to alter this behavior, you may register an custom implementation of springfox.documentation.spi.service.ExpandedParameterBuilderPlugin
interlace.
For e.g.
@Component
public class OverrideSwaggerApiParamNameBuilder implements ExpandedParameterBuilderPlugin {
@Override
public boolean supports(DocumentationType type) {
return DocumentationType.SWAGGER_2 == type;
}
@Override
public void apply(ParameterExpansionContext context) {
Optional<ApiParam> apiParamOptional = findApiParamAnnotation(context.getField().getRawMember());
if (apiParamOptional.isPresent()) {
fromApiParam(context, apiParamOptional.get());
}
}
private void fromApiParam(ParameterExpansionContext context, ApiParam apiParam) {
context.getParameterBuilder()
.name(emptyToNull(apiParam.name()));
}
private String emptyToNull(String str) {
return StringUtils.hasText(str) ? str : null;
}
}
Hope it helps.