SpringFox - 在 Swagger-ui 中隐藏调用端点时不需要的某些字段答案

【问题标题】：SpringFox - Hide certain fields in Swagger-ui that aren't required for the call to an endpointSpringFox - 在 Swagger-ui 中隐藏调用端点时不需要的某些字段
【发布时间】：2019-02-08 15:25:24
【问题描述】：

我想知道是否有任何方法可以让 SpringFox 不显示在调用特定端点时不需要的某个实体的所有字段。

例如：

具有以下实体：

public class Car {
    long id;
    String name;
    int wheels;
    String type;
    boolean canFly;
}

还有以下端点：

@RequestMapping(method = RequestMethod.GET,
                produces = MediaType.APPLICATION_JSON_VALUE)
public Car get(@RequestParam(value = "carId", required = true) long projectId) {
    return carService.get(carId);
}

@RequestMapping(method = RequestMethod.POST,
                consumes = MediaType.APPLICATION_JSON_VALUE,
                produces = MediaType.APPLICATION_JSON_VALUE)
public Car create(@RequestBody Car car) {
    return carService.create(car);
}

@RequestMapping(method = RequestMethod.PUT,
                consumes = MediaType.APPLICATION_JSON_VALUE,
                produces = MediaType.APPLICATION_JSON_VALUE)
public Car update(@RequestBody Car car) {
    return carService.update(car);
}

问题是在创建 Car 端点中只需要名称和车轮，但在文档中 Swagger-ui 显示所有字段就好像它们是必需的一样。我已经尝试过@JsonViews，但 Springfox 还没有处理它们。

有什么办法可以避免吗？

【问题讨论】：

标签： java spring swagger swagger-ui springfox

【解决方案1】：

使用@ApiModelProperty（来自io.swagger.annotations）

使用required，您可以定义该属性是强制的还是可选的。
使用hidden，您可以在 Swagger UI 中隐藏该属性，但如果已设置，则无论如何都会返回。

例如：

public class Car {

    @ApiModelProperty(value = "id", required = true)
    long id;

    @ApiModelProperty(value = "wheels", required = true)
    int wheels;

    @ApiModelProperty(value = "name", hidden = true)
    String name;

    @ApiModelProperty(value = "type", hidden = true)
    String type;

    @ApiModelProperty(value = "canFly", hidden = true)
    boolean canFly;
}

由于您对请求和响应使用相同的模型（上面的示例），因此 GET 端点文档中的属性也将被隐藏（请记住这一点）。如果您不想要这种行为，请使用单独的模型。

【讨论】：

目前看来，使用单独的模型是无法逃脱的。将不得不等到新版本的 SpringFox 发布然后

【解决方案2】：

从 springfox-boot-starter 3.0.0 开始

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>

您可以通过在需要的字段上添加 Jackson JsonProperty 注释来非常轻松有效地做到这一点。

@JsonProperty(access = JsonProperty.Access.READ_ONLY)

例如你有一个模型类 Client 并且你想要两者：

在请求（例如 POST 和 PUT）的 swagger 中隐藏字段 id，但在响应中显示它
不接受控制器中的字段 id（这样无论调用者设置什么，它总是具有值 0），而是在响应中返回客户端的 id 值。

您可以通过在 id 字段上添加注释来实现这些

import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Data;
@Data
public class Client {
    @JsonProperty(access = JsonProperty.Access.READ_ONLY)
    private long id;
    private String name;
}

【讨论】：