SpringFox Swagger - 模型中的可选和必填字段

Posted 2023-02-27

【中文标题】SpringFox Swagger - 模型中的可选和必填字段

【英文标题】：SpringFox Swagger - Optional and Mandatory fields in model

【发布时间】：2017-10-01 22:45:51

【问题描述】：

我使用 SpringFox 库作为我的 Spring Boot 应用程序的其余文档。当我单击 model 时，所有元素都作为可选元素返回。有没有办法将必需的元素显示为强制性的？是否需要添加任何额外的配置？

【参考方案1】：

在 Swagger 配置中尝试类似的代码：

    @Bean
public Docket api() 

    List<ResponseMessage> list = new java.util.ArrayList<>();
    list.add(new ResponseMessageBuilder().code(500).message("500 message")
            .responseModel(new ModelRef("JSONResult«string»")).build());
    list.add(new ResponseMessageBuilder().code(401).message("Unauthorized")
            .responseModel(new ModelRef("JSONResult«string»")).build());

    return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any()).build().securitySchemes(Collections.singletonList(securitySchema()))
            .securityContexts(Collections.singletonList(securityContext())).pathMapping("/")
            .directModelSubstitute(LocalDate.class, String.class).genericModelSubstitutes(ResponseEntity.class)
            .alternateTypeRules(newRule(
                    typeResolver.resolve(DeferredResult.class,
                    typeResolver.resolve(ResponseEntity.class, WildcardType.class)),
                    typeResolver.resolve(WildcardType.class)))
            .useDefaultResponseMessages(false).apiInfo(apiInfo()).globalResponseMessage(RequestMethod.GET, list)
            .globalResponseMessage(RequestMethod.POST, list);

并且在控制器映射中添加 @RequestBody @Valid MyRequestClass req 例如，如果您在请求正文中传递对象，并且如果您要传递参数，则添加类似 @RequestParam(value = "email", required = true, defaultValue = "") String email 的内容

另外，请参阅配置代码中如何引用具有泛型类型的类，即引用 JSONResult<String> 的 "JSONResult«string»"

【讨论】：

谢谢@Hasson。在传递 java 对象的选项中，如何使用此配置指定哪个字段是必填/可选的？

不确定 Swagger 是否会走得那么深，但您可以尝试将“@NotEmpty”和“@NotNull”用于传递的对象中的字段。

@PunterVicky 正如@Ganesh 的回答中所指出的那样。您可以使用@ApiModelProperty(required=true) 注释您的模型，或者使用@NotNull javax 注释对其进行注释。

谢谢@DilipKrishnan！

Springfox swagger v 2.8.0 似乎没有接受 @NotNull 注释； html 页面中的模型显示带/不带的字段没有区别。

【参考方案2】：

默认情况下是所有字段都是可选的。要根据需要标记字段，您可以使用以下注释。

@ApiModelProperty(required = true)

关于应该需要的字段的getter方法。 这不会将该字段显示为“必填”。但是文档中该字段的可选标签将被删除。

希望这会有所帮助。

【讨论】：

注释也适用于现场。生成的 Swagger 文档中的“模型”选项卡随后会显示一个星号以指示必需，并在字段后的新行上另外显示“allowEmptyValue：false”。

有没有办法将模型的所有字段设置为required，而不是在每个属性上写@ApiModelProperty(required = true)？

【参考方案3】：

添加了对 bean 验证注解的支持，特别是 Springfox v2.3.2 中的 @NotNull、@Min、@Max 和 @Size。

您可以将这些注释放在您的任何 API 模型上。

为了使用它，添加 springfox-bean-validators 依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-bean-validators</artifactId>
</dependency>

添加到应用程序的配置类：

@Import(springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration.class)

---

见：https://springfox.github.io/springfox/docs/current/#springfox-support-for-jsr-303

【讨论】：

谢谢，在添加 dep & import 后，模型生成的 Swagger UI 显示了字符串的最小和最大长度，很酷。但是我看不到注释 @NotNull 的整数字段有任何变化，我是瞎了吗？

@chrisinmtown 在我的 dto 中将 @NotNull 放在 int 或 Integer 上对我来说效果很好：在 swagger 文档的模型中，参数旁边会显示一个红星。如果您遇到问题，我会在 *** 或 springfox github 上提出一个新问题。

很遗憾，我发现这直到您也尝试自定义@ApiModelProperty。然后至少在 SpringFox 2.9.2 上，@NotNull 所需的方面丢失了，我也不得不用required=true 复制该信息。

这尊重群体吗？ IE。与@NotNull(groups = MyClass.class)--即@Validated 中只显示红色星号 MyClass 存在？

【参考方案4】：

我遇到了同样的问题，但是通过@etech 提示，我能够看到以大摇大摆的形式标记的必填字段。我所做的只是将 springfox-swagger.version 升级到 2.9.2（从 2.4.0）和 guava.version 到 20.0（从 15）加上应用程序配置类的导入。谢谢你。