如何描述请求体？

Question

我有一个WCF restful web服务。通常，我的每个端点都可以完美地描述/ service / help，因为它们只使用查询字符串作为输入参数。例如，我有以下简单的功能：

[WebInvoke(UriTemplate = "customer?name={name}", Method = "POST")]
public void customer(string name)

这显示在/ service / help中：

Service at http://localhost:7000/service/customer?name={NAME}

不幸的是，我无法在两种情况下这样做：

1. 具有令人难以置信的长值的端点（查询字符串被截断）
2. 包含敏感数据的端点（由IIS记录密码参数）

对于这两种情况，我知道需要传递一个请求体。将我的功能更改为：

[WebInvoke(UriTemplate = "customer", Method = "POST")]
public void customer(Stream requestBody)

现在/ service / help只返回

Service at http://localhost:7000/service/customer

如果我点击链接并导航到/ service / help / operations / customer，我也不会收到任何有用的信息：

The Request body is a byte stream

如何向API的使用者描述请求正文的XML / jSON结构？我可以以某种方式利用/服务/帮助，还是我被迫使用API​​文档？

Answer 1

我的第一个想法：我会说用in-url参数装饰所有API端点仅在某些时候有用，并且您确实应该为您提供信息的API构建完整的API文档关于/ service / customer等请求的预期输入和输出。

另外，为什么一个名字会长到一个网址被截断？如果我是你，我会认为1000个字符长的名称是无效输入，值得立即400: bad request回复