在 apiblueprint 中记录请求负载

Question

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

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

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

Headers

Content-Type: application/json

Body

{"id":"123"}

请求正文应该这么稀疏吗？向我的用户传达我的 REST 有效负载的所有 constraints/requirements 的最佳方式是什么？

Answer 1

如果我没理解错的话，您正在寻找一种方法来记录您的请求参数（headers、body 等）

如果是这样，则使用架构部分，并编写一个有据可查的文件 JSON-Schema

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

Request

    + Headers

        Content-Type: application/json

    + Schema

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

    + Body

    {"id":"123"}

在 apiblueprint 中记录请求负载

Documenting Request Payload in apiblueprint

rest

apiblueprint