如何手动描述 java @RequestBody Map<String, String> 的示例输入？

Posted 2023-02-27

【中文标题】如何手动描述 java @RequestBody Map<String, String> 的示例输入？

【英文标题】：How can I manually describe an example input for a java @RequestBody Map<String, String>?

【发布时间】：2017-06-11 04:45:44

【问题描述】：

我正在设计一个 API，其中一个 POST 方法采用任意键值对的 Map<String, String>。

@RequestMapping(value = "/start", method = RequestMethod.POST)
public void startProcess(
    @ApiParam(examples = @Example(value = 
        @ExampleProperty(
            mediaType="application/json",
            value = "\"userId\":\"1234\",\"userName\":\"JoshJ\""
        )
    ))
    @RequestBody(required = false) Map<String, String> fields) 
    // .. does stuff

我想为fields 提供一个示例输入，但我似乎无法让它在大摇大摆的输出中呈现。这不是@Example的正确使用方式吗？

【问题讨论】：

@ApiParam(value = "json", required = true,defaultValue = "\"id\": \"1\",\"deviceToken\":\"1\"" ,name = "json")

我正在尝试像上面那样。但仍然无法正常工作。它适用于标题

【参考方案1】：

Swagger 只提供 API，这些注解还是要集成到 Springfox 框架中才能工作。在发布此问题时，Springfox 既不支持 @ExampleProperty 也不支持 @Example。这可以在#853 和#1536 中看到。

从 2.9.0 版开始，这已经实现。例如，您可以查看this answer。

【讨论】：

现在还没有解决办法？如果它在那里，请帮助我。

@PrashanthDebbadwar 正如您在给定链接中看到的那样，问题仍然存在。目前票尚未处理，但他们正在寻找贡献。

你能告诉我们@ExampleProperty 的导入吗

【参考方案2】：

@g00glen00b 的回答中提到的问题似乎已经修复。这是如何完成的代码sn-p。

在你的控制器类中：

// omitted other annotations
@ApiImplicitParams(
        @ApiImplicitParam(
                name = "body",
                dataType = "ApplicationProperties",
                examples = @Example(
                        @ExampleProperty(
                                mediaType = "application/json",
                                value = "\"applicationName\":\"application-name\""
                        )
                )
        )
)
public Application updateApplicationName(
        @RequestBody Map<String, String> body
) 
    // ...


// Helper class for Swagger documentation - see http://springfox.github.io/springfox/docs/snapshot/#q27
public static class ApplicationProperties 

    private String applicationName;

    public String getApplicationName() 
        return applicationName;
    

    public void setApplicationName(String applicationName) 
        this.applicationName = applicationName;
    

此外，您需要将以下行添加到 Swagger 配置中：

// omitted other imports...
import com.fasterxml.classmate.TypeResolver;

@Bean
public Docket api(TypeResolver resolver) 
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo())
            // the following line is important!
            .additionalModels(resolver.resolve(DashboardController.ApplicationProperties.class));

更多文档可以在这里找到：http://springfox.github.io/springfox/docs/snapshot/#q27

【讨论】：

同意这个可行，但它只是..blah..如果可以省略dataType = "ApplicationProperties"会好得多

谢谢，它可以工作，但就像@EvgeniAtanasov 所说，我们最好删除模型类！