如何使 SpringFox Swagger 将字符串参数呈现为另一种模型类型？答案

【问题标题】：How to make SpringFox Swagger render a string parameter as another model type?如何使 SpringFox Swagger 将字符串参数呈现为另一种模型类型？
【发布时间】：2018-12-08 11:36:01
【问题描述】：

如何让 Swagger 将 String 资源参数记录为完整的类类型？

即我有这个资源声明：

@PatchMapping(path="/{id}")
public ApiResponse<MyObject> patch(@PathVariable String id, @RequestBody String myObjText) {

我希望 myObjText 被记录为具有 MyObject 类型的模型，同时仍然能够在方法主体中获取原始 JSON 文本（这是因为我稍后想通过 Jackson @987654327 调用 readerForUpdating() @)。

@ApiParam 似乎被 @RequestBody 参数忽略，并且那里不允许使用任何 @ApiModel* 注释。

我正在使用springfox，因为这些是 Spring Rest 资源。

【问题讨论】：

我认为这不能完成。如果请求正文是字符串类型，API 将接受任何字符串（不仅仅是 json 字符串）。 Spring 有一种自定义默认 ObjectMapper 的方法，您可以尝试。参考这里docs.spring.io/spring-boot/docs/current/reference/html/…
@Archit，我不担心验证或进一步的数据处理，我只是希望 documentation 比提供关于我的参数的通用 String 类型更具描述性格式
好的。那么也许您正在控制器代码中显式处理字符串验证，否则客户端可以使用任何随机有效负载调用 API。
@watery 我正在努力实现同样的目标。你找到解决办法了吗？
@Marc 我最终使用了Alexander Terekhov's answer - 请参阅更多 GitHub 问题。

标签： java swagger springfox

【解决方案1】：

尝试将字符串参数覆盖为@ApiParam(hidden = true) 并添加对象的新参数：

@ApiImplicitParams({
        @ApiImplicitParam(name = "My obj text",
        value = "myObjText", required = true,
        dataType = "com.example.MyObject", paramType = "body")
})

就像这里实现的一样： How to document implicitly dto usage, when we use entity class as api param?

【讨论】：

这不起作用（我想知道这是否可能是 Springfox 问题）。
当dataType 参数具有非包限定值时，这似乎有效，即dataType="MyObject"（参见SpringFox issue 2523）。
也许，我只用 Jersey 测试过。

【解决方案2】：

就我而言，需要进行两项更改：

1) 新增@ImplicitParams（类型名不符合包名）

@ApiImplicitParams({
    @ApiImplicitParam(name = "requestBody", required = true,
        dataType = "MyObject", paramType = "body")
})

2) 注册隐式模型类型（尤其是响应类型为ResponseEntity(Void.class)时

@Configuration
public class SwaggerConfiguration {

    @Autowired
    private TypeResolver typeResolver;

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
            .additionalModels(typeResolver.resolve(MyObject.class));
    }

}

【讨论】：