0

我有很多 API 端点要记录，POST 和 PUT 请求的负载可能很复杂。我正在用 apiblueprint 记录它们。我真的很喜欢 apiblueprint 允许我记录 URI 参数的方式。它看起来不错，可以让您向读者提供他们需要的所有信息，例如（必需、字符串或整数、列出选择/值并提供示例）。

当我们查看请求部分时，我没有看到如何提供相同级别的原始文档。我看到的请求部分只是提供了一个示例请求。

假设我们正在处理一个简单的有效负载，它只需要一个名为 id 的整数。目前我的请求部分看起来像这样，

标头

内容类型：应用程序/json

身体

{"id":"123"}

请求正文应该如此稀疏吗？向我的用户传达我的 REST 有效负载的所有约束/要求的最佳方式是什么？

4

1 回答 1

1

如果我理解正确，您正在寻找一种方法来记录您的请求参数（标题、正文等）

如果是这种情况，请使用 Schema 部分，并编写一个有据可查的 JSON-Schema

例如，您当前的简单请求将如下所示：

Request

    + Headers

        Content-Type: application/json

    + Schema

        {
            "type":"object",
            "properties":{
                "id": {
                    "type" : "string", 
                    "required": true
                }
            }
        }

    + Body

    {"id":"123"}
于 2015-03-11T04:17:15.133 回答