swagger @ApiParam忽略了某些属性

Question

我有一个Spring Boot项目,springfox-swagger2 2.7.0我有以下控制器:

@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 ...;
  }
...
}

我想通过注释Id类来控制文档中显示的内容,这仅适用于注释的某些部分,但不是全部.该Id班(其中有一个注册的转换器从String到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;
  }
}

现在Swagger JSON返回的内容如下:

"parameters":[{
  "name":"id",
  "in":"query",
  "description":"This is the description",
  "required":true,
  "type":"integer",
  "default":"1f1f1f",
  "format":"int64"
}]

我的问题(或可能是错误报告)是:为什么@ApiParam注释的某些部分被使用(比如value,defaultValue和required),但是其他部分不是,像name和type？为什么我似乎无法改变name或type在这里？对于我的特定用例,后者是我想要改变的用例string.

更新

我已经决定在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();
    }
  }
}

springfox的作​​者认为这可能是一个错误:https://github.com/springfox/springfox/issues/2107

Answer 1

默认情况下,@ ApacheParam属性'name'和'type'用于覆盖API方法中指定的参数名称和检测到的直接参数类型.在字段上使用@ApiParam时,类型和名称由字段名称推断,其声明的类型和名称和类型的覆盖值不予考虑.(它看起来像springfox中的设计,你可以看看实现springfox.documentation.swagger.readers.parameter.SwaggerExpandedParameterBuilder)

如果您仍希望更改此行为,则可以注册自定义的springfox.documentation.spi.service.ExpandedParameterBuilderPlugin交错实现.

例如

@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;
    }
}

希望能帮助到你.