swagger @ApiParam ignora certas propriedades

9

Eu tenho um projeto de inicialização com springfox-swagger2 2.7.0 E eu tenho o seguinte controlador:

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

Eu quero controlar o que é exibido nos documentos, anotando a classe Id , e isso está funcionando apenas para algumas partes da anotação, mas não para todas. A classe Id (que possui um conversor registrado de String para 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;
  }
}

Agora, o Swagger JSON retornado é o seguinte:

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

Minha pergunta (ou possivelmente relatório de bug) é: por que algumas partes da anotação @ApiParam são usadas (como value , defaultValue e required ), mas outras não, como name e %código%? Por que parece que não posso alterar o type ou name aqui? Para meu caso de uso específico, o último é o que eu gostaria de alterar para type .

Atualizar

Eu decidi adicionar o seguinte componente com a ajuda do 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();
    }
  }
}

Os autores do springfox sentem que isso pode ser um erro: link

    
por Michiel Haisma 15.11.2017 в 22:29
fonte

3 respostas

4

Por padrão, o atributo @ApiParam 'name' e 'type' são usados para substituir o nome do parâmetro e o tipo detectado de parâmetros diretos especificados no método da API. Quando você usa @ApiParam em um campo, o tipo e o nome são deduzidos pelo nome do campo e seu tipo declarado e o valor de substituição para nome e tipo não são considerados. (Parece por design no springfox, você pode dar uma olhada na implementação springfox.documentation.swagger.readers.parameter.SwaggerExpandedParameterBuilder )

Se você ainda deseja alterar esse comportamento, registre uma implementação personalizada de springfox.documentation.spi.service.ExpandedParameterBuilderPlugin interlace.

Por exemplo,

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

Espero que ajude.

    
por skadya 21.11.2017 / 23:59
fonte
-1

O ideal é usar @ApiParam com os parâmetros do método, enquanto @ApiModelProperty com as propriedades do modelo.

public @interface ApiParam {
    /**
     * The parameter name.
     * The name of the parameter will be derived from the field/method/parameter name,
     * however you can override it.
     * Path parameters must always be named as the path section they represent.
     */
    String name() default "";

Não tenho certeza se o atributo type está lá, mas abaixo está a maneira de lidar com os tipos:

public @interface ApiModelProperty {

    /**
     * The data type of the parameter.
     * This can be the class name or a primitive. The value will override the data type as read from the class
     * property.
     */
    String dataType() default "";

......
    
por Har Krishan 20.11.2017 / 13:59
fonte
-1

Estou usando a versão 2.6.1 e não consigo encontrar o atributo "type" em @ApiParam, enquanto vejo que você está usando "type" com isso. Portanto, verifique se ele está disponível para uso. Eu também mencionei @ApiModelProperty fornece dataType () para lidar com o cenário que você mencionou.

    
por Har Krishan 21.11.2017 / 09:22
fonte