记录没有正文但带有路径和查询参数的 PUT REST 调用

Question

有通过 HTTP PUT 设计的 REST API 调用，它只有路径和查询参数，不需要主体：

PUT /posts/{id}/read?currentUser={loginId}

尝试使用 Spring REST Docs 2.0 对其进行记录。0.RELEASE 我注意到 http-request.adoc 如下所示：

[source,http,options="nowrap"]
----
PUT /posts/42?currentUser=johndoe HTTP/1.1
Host: localhost:8080
Content-Type: application/x-www-form-urlencoded

currentUser=johndoe
----

我很困惑，为什么 currentUser=johndoe 在正文中呈现（如表单参数）？这是一个错误吗？下面是完整的应用示例：

@RestController
@RequestMapping("/posts")
@SpringBootApplication
public class DemoApplication {

    @PutMapping("{id}/read")
    public void markPostRead(@PathVariable("id") String id, @RequestParam("currentUser") String login) {
        System.out.println("User " + login + " has read post " + id);
    }

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

@RunWith(SpringRunner.class)
@WebMvcTest
public class DemoApplicationTests {

    @Rule
    public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
    private MockMvc mockMvc;

    @Autowired
    private WebApplicationContext context;

    @Before
    public void setUp() {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
                .apply(documentationConfiguration(this.restDocumentation))
                .build();
    }
    @Test
    public void contextLoads() throws Exception {
        mockMvc.perform(
                RestDocumentationRequestBuilders.put("/posts/{id}/read?currentUser=johndoe", 42))
                .andDo(document("mark-as-read", pathParameters(
                        parameterWithName("id").description("ID of the Post")
                )))
                .andDo(document("mark-as-read", requestParameters(
                        parameterWithName("currentUser").description("Login ID of user")
                )));
    }

}

Answer 1

如果你学习 RFC 2616 with special attention on the PUT section 你会读到...

The PUT method requests that the enclosed entity be stored under the supplied Request-URI.

所以问题是，尽管这部分规范不是 100% 清楚：是否允许发送根本没有请求主体的 PUT 请求？

这是其中一个问题，如果您询问 10 个开发人员，您会得到 11 个答案，但为了应对所有不可估量的问题，SpringREST Docs 将您的查询参数放在请求正文中以备不时之需对于所有那些更严格的网络服务器。 ;-)

Answer 2

此外，根据您的端点“@PutMapping("{id}/read")”，我注意到在您的 REST 文档测试中，路径的“/read”部分丢失了。

记录没有正文但带有路径和查询参数的 PUT REST 调用

Documenting PUT REST call without body and with path and query parameters

java

spring-restdocs