Rest Doc PUT带请求参数无请求体误设form-urlencoded内容类型问题咨询

根因说明 #

现有HttpRequestSnippet.java逻辑存在参数分类混淆，误将仅携带查询参数（Query Parameter）、无请求体的PUT请求判定为表单请求，强制设置了APPLICATION_FORM_URLENCODED_VALUE类型的Content-Type，不符合HTTP规范要求。

官方级适配修复方案 #

• 第一步：重构参数判定逻辑，严格区分查询参数、表单请求体参数、JSON/XML等自定义请求体三类场景，仅当请求携带表单参数且无自定义请求体时，才设置表单类型的Content-Type，仅携带查询参数的请求不触发该逻辑。
• 第二步：优化空请求体的Content-Type处理逻辑：
  可以新增NONE类型的MediaType常量，也可以直接复用现有*/*的ALL类型，更推荐的做法是直接省略Content-Type头——根据HTTP 1.1规范，无请求体的请求不需要显式声明Content-Type，兼容性更好。
• 第三步：补充测试覆盖以下场景，确保逻辑正确性：
  • PUT请求仅带查询参数、无请求体（对应你遇到的/api/v1/config/?mode=unknow场景）
  • PUT请求带表单参数、无查询参数
  • PUT请求同时带查询参数和表单参数

临时无需改源码的修复方案 #

如果暂时不改动Rest Doc的官方源码，可以自定义扩展HttpRequestSnippet覆盖默认逻辑：

public class CustomHttpRequestSnippet extends HttpRequestSnippet {
    @Override
    protected Map<String, Object> createModel(Operation operation) {
        Map<String, Object> model = super.createModel(operation);
        OperationRequest request = operation.getRequest();
        HttpHeaders headers = request.getHeaders();
        // 匹配仅带查询参数、无请求体、Content-Type被误设为表单的场景
        if (request.getContent().length == 0
                && !request.getParameters().isEmpty()
                && MediaType.APPLICATION_FORM_URLENCODED.equals(headers.getContentType())) {
            // 移除错误的Content-Type头
            headers.remove(HttpHeaders.CONTENT_TYPE);
        }
        model.put("headers", headers);
        return model;
    }
}

在生成API文档时，用自定义的CustomHttpRequestSnippet替换默认的HttpRequestSnippet即可生效。

内容的提问来源于stack exchange，提问作者Venkat Bontha